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Introduction 


Facebook  has  grown  phenomenally  over  the  past  several  years 
from  an  Ivy  League  social  web  application  to  one  of  the  top  ten 
most  visited  web  sites  on  the  internet.  It  currently  has  more  than 
250  million  active  users  and  more  than  350,000  active  applications 
with  billions  of  page  views  per  month. 

It  comes  with  its  own  platform  for  application  development  which 
consists  of  an  HTML-based  markup  language  called  Facebook 
Markup  Language  (FBML),  an  application  programming  interface 
(API)  for  making  representational  state  transfer  (REST)  calls  to 
Facebook,  a  SQL-styled  query  language  for  interacting  with  Facebook 
called  Facebook  Query  Language  (FQL),  a  scripting  language  called 
Facebook  JavaScript  for  enriching  the  user  experience,  and  a  set  of 
client  programming  libraries.  Facebook  applications  are  hosted  on 
the  application  developer's  own  server,  but  because  of  the  way  they 
interface  with  Facebook,  they  appear  to  users  to  be  part  of  Facebook 
itself.  Using  Facebook  applications,  developers  can  add  custom  features 
and  new  ways  for  users  to  interact  with  each  other  using  Facebook. 

We'll  help  you  get  started  on  building  powerful  Facebook  applications , 
and  details  how  to  use  the  core  technologies  of  the  Facebook  Platform 
to  create  an  application,  how  to  deploy,  monitor,  and  tune  it,  how  to 
work  with  data  stored  in  Facebook,  including  photos,  how  to  handle 
multimedia  and  other  custom  data  within  Facebook  applications,  how 
to  send  notifications  and  invitations  from  within  an  application,  update 
a  user's  profile,  how  to  create  application  control  panels  for  users,  and 
much  more. 

Hopefully,  this  book  will  go  a  long  way  into  making  you  understand 
what  makes  applications  work  on  Facebook,  how  to  monitor  their 
progress,  and  make  changes  that  maximise  their  potential  for  success. 
This  book  will  not  only  act  as  a  reference  for  the  various  parts  of  the 
Facebook  Platform,  but  also  address  the  entire  process  of  creating 
applications  from  inception  to  deployment  and  beyond.  Besides  taking 
you  through  the  necessary  steps  to  getting  your  application  built  in  the 
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best  way  possible,  this  book  also  teaches  you  how  to  maximise  your 
chances  of  getting  your  application  to  spread  successfully  and  make 
money  out  of  it. 

Chapter  1,  2,  and  3  introduce  you  to  the  basic  Facebook  application 
architecture,  integration  points,  and  the  elements  used  by  your 
application  to  interface  with  Facebook,  i.e.,  the  Facebook  Platform  that 
consists  of  the  Facebook  API,  FBML  and  FQL.  It  acts  as  a  primer  to 
making  successful  Facebook  applications  and  a  quick  reference  to  the 
key  points  in  Facebook  application  development. 

Chapter  4,  5  and  6  explains  the  tools  of  the  Facebook  platform 
in  detail,  and  analyse  the  technique  used  to  work  with  them,  using 
various  examples.  This  will  cover  the  essentials  needed  to  get  you 
started  on  application  development,  along  with  setting  up  a  developer 
environment,  getting  the  necessary  tools  and  how  to  use  and  test  your 
code  using  the  test  consoles  on  Facebook.  You  will  also  be  shown  the 
scripting  ability  in  Facebook,  using  a  subset  of  standard  JavaScript 
functions  in  FJS.  It  will  also  serve  as  an  introduction  to  Facebook  Query 
Language  (FQL),  which  is  sometimes  more  effective  to  use  than  the 
Facebook  REST  API 

Chapter  7  will  cover  Profile  pages  and  how  to  extract  the  Facebook 
information  to  be  displayed  by  your  application,  store  information  in 
the  Facebook  cache  and  display  it  on  your  users'  Profile  pages,  and  store 
your  own  custom  data. 

Chapter  8  will  cover  the  details  of  managing  feeds  (both  news  feed 
and  mini  feed)  using  Facebook  REST  APIs.  It  will  also  cover  Publisher, 
which  is  very  similar  to  Feeds. 

Chapter  9  will  focus  on  creating  a  successful  invitation  and 
notification  system,  with  source  code  snippets  on  how  to  create 
a  successful  notification  system,  use  notifications  efficiently,  and 
send  emails. 

Chapter  10  will  detail  the  methods  for  spreading  your  application, 
measuring  its  success  and  making  money  out  of  it.  It  will  also  provide 
you  help  resources  and  references  in  case  you  bump  into  any  problem 
during  development.  H 
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The  Facebook  platform  consists  of  various  elements  that  allow  application 
developers  to  build  an  application  and  replicate  the  look  and  feel  of 
Facebook  within  it.  These  elements  are  mostly  derived  from  well-known 
web  development  languages  such  as  HTML,  SQL  and  JavaScript  for  easy 
portability.  They  are: 

The  API  (Application  Programming  Interface),  also  known  as  the  REST 
API  that  handles  communication  and  function  calls  between  Facebook  and 
your  application. 

•  FBML  (Facebook  Markup  Language),  a  markup  language  derived  from 
HTML 

•  FQL  (Facebook  Query  Language),  for  data  handling. 

•  Facebook  JavaScript,  for  scripting  needs. 

•  Client  libraries  for  programming  languages. 

Let  us  look  at  all  of  these  components  in  detail  to  understand  the  need  and 
use  of  them  while  making  powerful  yet  simple  Facebook  applications. 

1.1  FBML  (Facebook  Markup  Language) 

It  is  a  tag-based  programming  language  like  HTML  used  to  format  your 
information,  albeit  a  bit  more  fancy  as  each  interaction  starts  and  ends 
with  a  tag.  FBML  provides  a  large  set  of  Facebook  user  interface  and 
programmatic  primitives  required  to  abstract  complex  code  and  make 
most  routine  procedures  effortless.  The  tags  are  automatically  parsed  and 
translated  into  HTML,  CSS  (Cascading  Style  Sheets),  and  JavaScript  code  by 
Facebook  servers  when  a  request  for  an  application  page  that  contains  it  is 
detected.  If  you've  previously  used  HTML,  then  you  will  have  no  problems 


thinkdfflt 


7 


FAST  TRACK-  APRIL  2010 


D  The  Facebook  platform 


Creating  Facebook  Apps 


adapting  to  FBML.  To  distinguish  between  HTML  and  FBML  commands  in 
your  application  code,  you  need  to  prefix  FBML  tags  with  fb:  as  you  would  if 
you  were  using  multiple  DTDs/schemas  in  XHTML. 

For  example,  if  you  want  to  add  a  link  to  your  application's  about 
page  on  your  dashboard,  all  you  need  is  to  add  the  following  lines  of  code  in 
your  application: 

<fb : dashboard> 

<fb: about  href ="about .php">About  the  Application</ 
fb: about> 

</f b : dashboard> 

1.2  FQL  (Facebook  Query  Language) 

FQL  stands  for  Facebook  Query  Language.  It  offers  a  lot  of  SQL-like  features 
and  language  elements  that  allow  applications  to  directly  query  Facebook's 
internal  data  tables.  FQL  uses  the  same  syntax  as  typical  ANSI-SQL,  so  if 
you've  worked  with  SQL  before,  FQL  isn't  a  big  deal.  FQL  is  powerful  in  the 
sense  that  it  accesses  and  returns  the  same  data  provided  by  many  of  the 
Facebook  API  calls;  however,  it  allows  applications  to  have  Facebook  filter 
that  data  with  a  language  of  your  choice  before  it's  returned  to  the  client, 
which  potentially  speeds  up  page  loading  and  response  times. 

For  example,  if  you  want  the  name,  and  birthday  of  all  of  your  friends, 
then  you  can  use  the  following  query  in  the  API  Test  Console: 

SELECT  first  name,    last  name,  birthday 

FROM  user 

WHERE  uid  IN    (        SELECT  uidl 
FROM  friend 
WHERE  uid2=1234646) 
Don't  forget  to  replace  our  ID  (1234646)  with  your  own  because  you  can  only 
use  the  details  of  friends  of  the  logged  in  user.  We  are  still  using  the  API,  but 
only  one  method— fql.query.  This  basically  means  that  you're  not  limited  to  the 
information  supplied  by  the  API  methods  and  the  FBML  tags.  You  can  actually 
extract  the  exact  data  that  you  want  with  whatever  language  you  are  using. 

1.3  FBJS  (Facebook  JasaScript) 

FBJS  is  the  Facebook's  version  of  JavaScript  for  developers  who  really  want, 
or  need,  to  use  JavaScript  in  their  applications.  Facebook  scrubs  (removes) 
much  of  the  JavaScript  you  add  to  your  application  to  minimise  the  threat  of 
cross-site  scripting  (XSS)  attacks,  but  by  using  Facebook  JavaScript  (FBJS) 
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you  can  still  enrich  the  user's  experience.  It  supports  most  of  the  DOM-based 
manipulation  methods  of  JavaScript  and  the  familiar  events,  functions, 
anonymous  closures,  and  properties.  If  you're  familiar  JavaScript,  you'll  pick 
this  up  quickly  (or  perhaps  find  it  maddening!).  For  example,  if  you  want  to 
provide  a  modal  dialog  box  to  your  users: 

<a  href="#"  onclick="new  Dialog (). showMessage (' Dialog ' , 
'Message 

for  this  link '); return  false">Show  Dialog  Box</a> 
When  this  code  gets  processed  by  the  Facebook  platform,  a  user  will  be 
shown  the  modal  dialog  box  after  clicking  the  Show  Dialog  Box  hyperlink. 
Pretty  good  for  a  single  line  of  code!  It  however  differs  from  JavaScript  in 
many  ways.  The  syntax  is  slightly  different,  primarily  to  protect  Facebook 
itself  from  malicious  JavaScript  code  and  cross-site  scripting  (XSS)  attacks. 
Many  DOM  properties  used  in  normal  JavaScript  are  replaced  by  get/set 
property  methods.  Finally,  some  event  handlers  are  not  available  that  are 
widely  used  in  normal  client-side  JavaScript.  The  use  of  the  ubiquitous 
onload  ()  event  handler  to  execute  code  when  a  web  page  loads  is  not 
allowed.  A  user  must  take  an  action  on  the  page  (set  focus  to  a  control,  click  a 
mouse  button,  hit  a  key)  before  FBJS  can  execute  in  most  locations.  Facebook 
also  wraps  all  FBJS  in  a  sandbox.  Basically,  all  FBJS  variables,  function 
names,  and  function  parameters  are  prepended  with  a  special  string  that 
ensures  that  no  FBJS  code  conflicts  with  or  can  override  any  existing 
JavaScript  code  that  might  be  on  the  page. 

1.4  XFBML  and  the  Facebook  JavaScript  Client  Library 

Applications  which  are  based  on  IFrames  and  external  sites  that  use  Facebook 
Connect  do  not  have  access  to  FBML  because  of  platform  limitations  and, 
therefore,  don't  get  access  to  a  lot  of  the  Facebook  controls  and  widgets 
it  provides.  To  overcome  these  limitations,  Facebook  provides  XFBML 
as  well  as  the  Facebook  JavaScript  Client  Library  which  give  developers 
access  to  most  of  the  features  provided  by  FBML.  Applications  that  use 
XFBML  render  their  pages  using  strict  XHTML  and  load  the  Facebook 
JavaScript  Client  Library  to  get  access  to  its  features.  These  applications 
use  the  Facebook  API  on  the  client  rather  than  the  server.  This  means  that 
a  Facebook  application  can  run  anywhere  and  not  just  inside  Facebook. 
Features  such  as  logging  in  with  Facebook  credentials  and  publishing  news 
stories  are  available  in  any  web  browser  thanks  to  this. 

After  the  page  loads  and  initializes  the  Facebook  JavaScript  Client 
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Library,  it  can  call  the  API  functions  and  use  XFBML  which  can  either  be 
displayed  inline  on  the  page  or  dynamically  created  via  the  library. 

1.5  Application  architecture 

All  Facebook  applications  have  the  same  basic  architecture  to  interoperate 
with  the  Platform.  For  this  reason,  Facebook  provides  a  Facebook  Developer 
application  to  allow  developers  to  make  new  applications  and  add  in  the 
details  where  they  are  hosted.  Each  application  is  issued  a  secret  identifying 
keys,  and  developers  are  required  to  enter  URLs  for  how  users  and  Facebook 
access  the  application. 

This  does  not  mean  that  Facebook  actually  host  developer's  applications. 
It  simply  acts  as  a  proxy  instead  so  that  when  the  user  visits  the  Canvas 
Page  URL,  Facebook  creates  an  outer  frame  and  then  calls  the  application's 
Canvas  Callback  URL  to  get  information  to  display. 

1.5.1  Secret  Keys 

Whenever  an  application  is  created  on  the  Facebook  Developer  platform,  it 
is  given  a  public  and  private  key  pair.  The  public  key  is  called  the  API  key, 
and  the  private  key  is  called  the  Secret  key.  These  keys  verify  that  all  calls 
made  to  the  Facebook  API  are  from  that  very  application.  It  is  an  important 
security  feature  and  developers  should  protect  their  Secret  keys  and  report 
their  loss  if  they  are  ever  compromised.  Otherwise,  any  other  application 
can  start  making  calls  masquerading  as  that  application,  and  modify  or  even 
delete  user  data. 

1.5.2  Canvas  Page  URL 

The  Canvas  Page  URL  is  the  URL  that  Facebook  users  use  to  get  to  the  application. 
It  is  of  the  format  http://apps.facebook.com/canvaspageurl.  It  needs  to  be  unique. 

1.5.3  Canvas  Callback  URL 

The  Canvas  Callback  URL  is  the  URL  of  your  server  where  your  application 
resides.  Facebook  makes  calls  to  this  URL  whenever  it  needs  to  display 
an  application  page,  or  when  a  user  adds  or  removes  the  application,  or 
when  it  needs  to  update  its  cache.  The  server  hosting  the  Canvas  Callback 
URL  should  be  able  to  handle  the  callbacks  using  whatever  web  server  or 
language  the  developer  deems  appropriate.  Facebook  sends  the  set  of  data 
as  POST  variables  to  the  Canvas  Callback  URL,  which  contains  information 
about  the  viewing  user,  the  session,  and  the  application. 
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1.5.4  Canvas  Page  Workflow 

Whenever  a  user  accesses  an  application  canvas  page,  Facebook  calls  the 
application's  Canvas  Callback  URL.  Your  Facebook  applications  can  either 
have  FBML  or  IFrame  based  canvas  pages.  The  biggest  difference  here  is  that 
applications  that  produce  FBML  requires  Facebook  to  render  their  content 
before  displaying  it.  This  is  so  that  Facebook  can  convert  each  FBML  control 
into  its  HTML  and  JavaScript  equivalents  for  your  web  browser.  IFrame- 
based  canvas  pages  just  show  their  content  directly. 

1.6  Facebook  Mobile  Support 

Facebook  provides  rich  mobile  integration  for  most  mobile  phones  and 
even  supports  the  iPhone  with  the  Facebook  Connect  for  iPhone  library. 
The  integration  points  are  generally  the  Facebook's  mobile  web  site  -  http://m. 
facebook.com  or  the  use  of  Facebook's  Short  Message  Service  (SMS,  or  text 
messaging)  service. 

Mobile  applications  for  the  mobile  Facebook  web  site  use  only  a  subset 
of  FBML  to  create  mobile  profile  and  canvas  pages.  A  special  fb  sig  mobile 
parameter  is  passed  to  the  application  as  a  POST  variable  whenever  a  mobile 
browser  is  detected  by  the  Facebook  servers.  The  application  then  returns 
only  the  FBML  enclosed  in  special  <fb:mobile>  tags  for  display.  Mock 
AJAX  and  FBJS  are  yet  not  available  in  this  version. 

The  user  needs  to  go  to  the  Settings  page  on  http://rn.facebook.com  and  enable 
the  application  to  show  up  on  her  mobile  profile  even  after  he  has  added 
the  application. 

Facebook's  SMS  service  lets  applications  send  and  receive  SMS 
notifications.  Again,  the  user  must  first  allow  this  feature  by  enabling  the 
SMS  extended  permission  in  the  application.  To  check  whether  a  user  has 
set  permissions,  you  can  call  the  sms .  canSend  ( )  API  function.  Once  the 
permissions  have  been  granted,  applications  can  send  an  SMS  notification  or 
start  an  SMS  conversation,  depending  on  the  parameters  to  the  API  call.  The 
user  can  also  reply  to  the  SMS  or  follow  a  link  inside  of  it  to  the  application's 
mobile  Facebook  Page. 

The  API  wrapper  code  for  handling  SMS  calls  is  not  yet  part  of  the  PHP 
client  library.  However,  Facebook  Connect  for  the  iPhone  library  allows 
iPhone  developers  to  include  an  Xcode  project  into  their  applications.  iPhone 
applications  will  be  able  to  access  the  Facebook  Platform  API  to  get  user 
information,  set  a  status,  create  a  news  story,  and  get  friend  information  with 
the  help  of  this.  0 


thinkd\9\t 


11 


FAST  TRACK-  APRIL  2010 


Win!! 

Exciting  Prizes 
worth  Rs.20000 

What  you  learn  from  this  Fast  Track  could  win 
you  Rs.  20,000  in  exciting  prizes.  Take  part  in 
Digit's  Facebook  Apps  contest  by  going  to 

www.thinkdigit.com/d/fb_contest 


□  The  Facebook  API 


The  Facebook  API  (or  Application  Programming  Interface)  is  a  set  of 
software  libraries  that  enable  you  to  work  with  Facebook  without  knowing 
anything  about  its  internal  workings.  All  you  have  to  do  is  obtain  the  client 
libraries,  and  start  making  use  of  them  in  your  own  application. 

2.1  The  classification 

Facebook  API  calls  are  grouped  into  various  action  categories,  each  of 
which  focuses  on  a  different  aspect  of  the  Platform.  These  methods  are 
really  wrappers  for  more  sophisticated  FQL  interactions  with  the  Facebook 
back  end  but  are  useful  bits  of  code  that  speed  up  the  development  of  your 
application.  Before  we  get  into  the  details  of  these  categories,  let  us  look  at 
some  basic  ones: 

•  facebook.auth  -  basic  authentication  checks  for  Facebook  users. 

•  facebook.feed  -  post  to  Facebook  news  feeds. 

•  facebook.friends  -  query  Facebook  for  various  checks  on  a  user's  friends. 

•  facebook.notifications  -  send  messages  to  users. 

•  facebook.profile  -  set  FBML  in  a  user's  profile. 

•  facebook.users  -information  about  your  users  (such  as  content  from  the 
user's  profile  and  whether  they  are  logged  in). 

•  facebook.events  -ways  to  access  Facebook  events. 

•  facebook.groups  -  access  information  for  Facebook  groups. 

•  facebook.photos  -  interact  with  Facebook  photos. 

Facebook  consistently  modifies  these  APIs  as  part  of  the  REST  API 
as  new  features  are  added,  security  issues  are  addressed,  or  behaviour 
deprecates  or  becomes  obsolete. 

Authentication  API 

The  Facebook  REST  API  has  two  methods  facebook.auth.createToken  and 
f acebook.auth.getSession  for  dealing  with  authenticating  yourusers.facebook. 
auth .  createToken  is  the  method  that  creates  an  authentication  token  (auth_ 
token)  that  is  then  passed  to  the  Facebook  authentication  mechanism.  Once  the 
user  is  logged  in,  the  second  method,  facebook.auth.getSession  will  contain  this 
token  in  the  response  if  you  specifically  request  the  auth  token  in  the  response. 

Because  Facebook  takes  responsibility  for  these  actions,  you  don't  have 
to  take  the  headache  of  authentication  and  purchase  SSL  certifications, 
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implement  your  own  encryption  schema  for  passwords,  or  even  worry  about 
sessions.  In  our  case  while  working  with  the  PHP  client  library,  you  start 
the  authentication  procedure  by  calling  the  Facebook  object's  require  login 
method.  Your  users  are  then  redirected  to  Facebook's  login  page  (https://login. 
facebook.com/login.php),  which  is  passed  with  your  API  key,  and  the  user  is  given 
a  session  key  and  redirected  to  your  callback  page.  When  the  user  enters  the 
application  for  the  first  time,  he  is  asked  to  accept  the  terms  of  service  for 
your  application. 

Instead  of  logging  into  Facebook  every  time  you  want  to  update  the  data 
to  use  some  sort  of  scheduled  task,  you  can  do  so  with  an  infinite  session  key. 
The  process  to  get  your  infinite  key  is  however,  a  bit  more  convoluted.  After 
you've  made  your  application,  create  a  new  page  (inf  inite  key  .php) 
on  your  server,  i.e.,  your  callback  domain.  This  will  create  a  new  Facebook 
object  and  echo  your  session  key: 

<?php 

$f acebook_conf ig [' debug ' ]   =  false; 

$facebook  config['api  key']   =   '<your  api  key>'; 

$facebook  config [' secret  key']   =   '<your  secret  key> ' ; 

require_once ( ' <path_to_api>/ facebook. php ' ) ; 

$ facebook  =  new  Facebook ($facebook_conf ig [' api_key ']  , 

$f acebook_conf ig [ ' secret ' ] )  ; 

$user  =  $f acebook->require  login (); 

$infinate  key  =  $f acebook->api  client->session  key; 

echo ($ inf inate_key) ; 

?> 

Now  log  out  of  Facebook,  clear  your  Facebook  cookies  and  browser 
cache,  and  then  go  to  the  page  you  just  created  on  your  server.  Once  you've 
logged  on,  you  should  see  the  infinite  key  that  you  can  then  use  in  your  code. 
You  can  now  use  your  own  UID  and  the  key  just  obtained  in  other  code  to 
perform  anything  that  needs  to  happen  on  a  regular  basis  with  the  set_user 
function  in  the  facebook  object: 

<?php 


$uid  =   '<your  uid> ' ; 

$key  =   '<your  infinite  key> ' ; 

$facebook->set_user ($uid,    $key) ; 

/ /  other  code 

?> 


FAST  TRACK -APRIt  2010 


14 


thinkd\9\t 


Creating  Facebook  Apps 


The  Facebook  API  B 


Permissions  API 

The  permissions  API  contains  functions  and  methods  to  manage  applications' 
developer  settings,  retrieve  application  Facebook  metrics,  ban  specific  users, 
automate  application  configuration  and  setup  on  different  servers,  and  get 
application  public  information  to  control  overall  application  management. 

Authorization  API 

The  Authorization  API  contains  functions  and  methods  used  for  handling 
session  management  and  login  information  on  both  desktop  or  external 
Facebook  applications. 

Batching  API 

The  slowest  part  of  a  web  application  is  waiting  for  the  data  requested 
from  some  remote  source  to  be  returned  because  communicating  with  a 
remote  server  via  HTTP  or  any  protocol  is  expensive  in  terms  of  response 
time  and  latency.  Facebook  applications  fall  in  the  same  category  and  are 
no  exception  to  this.  The  Batching  API  allows  applications  to  bundle  up  to 
20  API  calls  and  make  a  single  call  to  a  remote  Facebook  server  instead  of 
several  individual  ones.  This  significantly  speeds  up  that  part  of  a  Facebook 
application.  It  is  even  configurable  in  the  sense  that  these  calls  can  be  made 
sequentially  or  in  parallel,  depending  on  the  application's  needs. 

Comments  API  (Beta) 

The  Comments  API  includes  methods  that  allow  applications  to  comment  on 
individual  Feed  stories  and  add  it  to  the  stream  along  with  the  ability  to  get 
and  remove  these  comments  programmatically. 

Data  Store  API 

The  DataStore  API  provides  methods  for  basic  database  manipulations  offline 
caching  of  data  with  basic  create,  read,  update,  and  delete  (CRUD)  calls  for 
storing  data  that  you  access  through  REST.  This  follows  the  object-oriented 
database  management  systems  (OODMSs),  which  is  a  bit  different  from  the 
relational  database  management  systems  (RDBMSs)  in  terms  of  terminology. 

To  use  the  Data  Store  API,  you  need  to  define  your  schema  (your 
database),  which  consists  of  object  types  (tables)  and  properties  (columns). 
Facebook's  servers  perform  your  database  manipulations  for  you.  However, 
there  aren't  any  structured  queries,  full-text  search,  or  transaction-level 
query  processing  in  the  Facebook  Data  Store  API. 
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There  are  three  basic  functions  in  the  DataStore  API:  specialized  tables, 
distributed  tables,  and  associations  that  are  split  into  five  separate  APIs 
(User  Preference,  Object  Data  Definition,  Object  Data  Access,  Association 
Data  Definition,  and  Association  Data  Access). 

According  to  Facebook,  it  can  handle  millions  of  records  with  little  or  no 
performance  degradation,  something  we  can't  be  sure  of  about  data  stored 
on  local  servers.  Because  indexing  tables  in  a  distributed  environment  won't 
necessarily  provide  a  performance  boost,  Facebook  provides  a  specialized 
table  of  users  that  is  optimized  to  provide  performance  for  fast  lookups 
(such  as  indexes)  with  the  help  of  the  associations  component  of  this  API. 
This  mechanism  has  been  implemented  to  provide  fast  lookups  without 
centralized  indexes  or  parallel  queries.  The  user  preferences  for  the  API 
are  a  list  of  128-character  strings,  for  which  you  can  store  up  to  201  for 
each  user  (numbered  0-200).  Access  to  the  getters/setters  methods  are 
accessed  through  getters  and  setters  in  the  REST  API  (facebook. data. 
setUserPref erence  and  facebook . data . getUserPref erences). 

Data  objects  can  be  created  with  facebook .  createOb  j  ectType.  These 
objects  takes  a  name  and  contains  a  set  of  object  properties  like  data  types. 
However,  you  don't  have  the  same  type  of  control  over  the  data  types  with 
this  API  as  you  do  with  normal  RDBMS  because  you  are  limited  to  integers, 
strings  (less  than  256  characters),  and  text  blobs  (with  a  maximum  of  64  KB). 

You  create,  read,  update,  and  delete  through  the  Object  Data  Access  API 
after  you  have  defined  your  objects  and  object  types.  These  go  like  facebook . 
data  .  createOb  j  ect.  But,  you  first  need  to  define  the  relationship  between 
objects  in  the  facebook .  def  ineAssociation  call  to  work  with  the 
associations  between  objects.  There  are  two  basic  types  of  associations:  one- 
way, symmetric  associations  and  asymmetric  associations.  The  asymmetric 
association  is  like  a  many-to-many  join  and  a  symmetric  association  is  like  a 
one-to-many  join.  You  can  then  create  the  actual  associations  with  the  help  of 
the  Association  Data  Access  API  which  contains  methods  required  to  create, 
remove,  and  retrieve  these  associations  and  retrieve  the  object  details  from 
the  data  contained  in  the  data  definition. 

Example: 

<?php 

$ createOb j ect  =  $ f acebook->api_cl ient->data_ 
createOb j ectType ( "wallpost" ) ; 

$uid  =  $f acebook->api_client->data_def ineObjectProperty 
("wallpost",    "uid",  1); 
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$time  =  $f acebook->api_client->data_def ineObj ectPropert 
y  ( "wallpost" ,    "timePosted",  2); 

$post  =  $facebook->api_client->data_defineObjectPropert 
y ("wallpost",    "post",  3); 

?> 

This  code  snipped  is  analogous  to  the  SQL: 

CREATE  TABLE  wallpost ( 
uid  integer, 
timePosted  timestamp, 
post  text 
) 

It  takes  a  little  bit  to  get  used  to  the  DataStore  API  because  you're  not 
performing  typical  SQL  DDL;  but  once  you  get  yourself  around  creating  the 
objects,  it  becomes  relatively  trivial  to  use  the  API  as  the  persistence  layer  for 
your  application.  This  API  is  a  boost  for  those  who  choose  to  have  Facebook 
manage  their  data  instead  of  writing  their  own  SQL  queries  and  using  the 
client  library  to  manage  data. 

Events  API 

Facebook  has  rich  event  system,  which  allows  users  to  create  events  with 
built-in  RSVP  features,  event-specific  media,  and  export  capabilities.  The 
events  API  allows  applications  to  manage  events  on  its  users'  behalf 
with  two  main  wrappers  to  retrieve  information  on  events,  facebook . 
events  .get  method  returns  a  response  based  on  the  filters  passed  to  it 
and  the  facebook. events  . getMembers  method  returns  the  RSVP  status 
for  Facebook  members  for  a  given  event.  These  methods  requires  extra 
permissions  from  the  user. 

FBML  API 

The  FBML  API  is  a  set  methods  that  allow  developers  to  create  custom  FBML 
tags,  refresh  cached  images,  upload  localized  strings  for  internationalisation, 
and  do  high-performance  updates  of  cached  profile  box  FBML.  The 
facebook.  fbml .  ref  reshlmgSrc  method  is  used  to  fetch  and  catch  an 
image  at  a  given  URL.  The  facebook .  fbml .  ref  reshRefUrl  method 
is  used  to  refresh  content  from  a  given  URL  and  the  facebook.  fbml . 
setRef  Handles  method  is  used  to  get  content  as  a  handle  in  FBML.  You 
can  even  register  custom  FBML  tags  with  Facebook  and  make  them  public 
so  that  other  developers  can  use  them  in  their  own  applications. 
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Feed  API 

The  Feed  API  contains  methods  that  allows  applications  to  register  templates 
for  the  stories  they  publish  to  the  stream  and  to  directly  publish  these  stories 
programmatically.  To  publish  information  to  an  individual  user's  feed,  use 
the  facebook.  feed. publishStoryToUser  method  and  the  information 
will  get  published  to  a  user's  feed  based  on  their  session  key  (session  key) 
and  their  user  ID  (uid).  The  facebook.  feed. publishActionOfUser 
method  can  be  used  to  publishe  a  mini-feed  story  to  the  user's  account,  also 
based  on  their  session  key  and  user  ID. 

Friends  API 

Friends  API  allows  your  application  to  look  at  the  friends  of  your  users.  The 
method  facebook .  friends  .  areFriends  can  be  used  to  get  whether 
two  people  are  friends.  The  facebook  .  friends  .  get  method  can  be  used 
to  return  a  structure  of  the  user's  friends'  user  IDs.  Also,  the  facebook. 
friends .  getAppUsers  method  can  be  used  to  return  a  structure  of  the 
friends  of  the  user  who  have  installed  the  application  on  which  you're  working. 

FOL  API 

FQL  API  allows  calls  which  are  wrappers  for  complex,  but  common,  FQL 
queries  so  that  developers  can  access  information  provided  by  API  methods, 
but  by  using  a  SQL-like  query  language.  Many  of  Facebook's  API  methods 
use  FQL  internally  to  access  the  data  they  return  or  need.  In  general,  it  is  more 
efficient  to  use  a  FQL  query  than  an  equivalent  API  call.  The  facebook.fql 
method  will  take  a  query  and  return  a  response  object  based  on  your  syntax. 

Groups  API 

If  you  want  your  application  to  work  with  your  user's  groups,  the  Groups 
API  has  two  methods  that  return  information  about  their  visible  groups. 
You  can  either  retrieve  all  the  groups  the  user  belongs  to  or  a  subset  of  these 
groups  with  the  facebook.  groups .  get  method  or  use  the  facebook. 
groups  .getMembers  method  to  return  the  user  IDs  (UIDs)  for  a  given 
public  group. 

Links  API 

The  links  API  contains  methods  that  allow  applications  to  give  its  users  the 
ability  to  post  links  to  their  Walls  directly  from  the  application.  These  API 
method  calls  work  in  a  similar  way  as  the  ubiquitous  Facebook  Share  button. 
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User  Management  API 

The  User  Management  API  is  probably  the  most  frequently  used  set  of  APIs 
in  the  Facebook  Platform,  because  it  provides  your  applications  direct  access 
to  the  users  and  their  information  in  the  social  graph.  These  APIs  contain 
methods  required  for  getting  users'  friends,  individual  user's  information, 
verifying  if  specific  users  have  authorised  your  application,  and  organising 
lists  of  friends,  facebook .  users  .  isAppAdded  method  tells  you  whether 
the  user  has  added  your  application.  If  you  with  to  get  information  from  your 
user's  profile,  you  can  call  the  method  facebook  .users  .  getlnf  o.  To  get 
the  user  ID  (uid)  from  a  session  key,  you  need  to  use  the  facebook  .users . 
getLoggedlnUser  method. 

Marketplace  API 

Facebook  has  its  own  marketplace  where  users  can  buy/sell  items,  list  jobs,  list 
housing,  or  even  request  items  to  purchase/borrow.  To  enable  your  application  to 
search  the  Facebook  marketplace,  use  the  facebook.  marketplace .  search 
method.  To  get/set  listings,  the  facebook .  marketplace .  getListings  and 
facebook .  marketplace  .  createListing  are  helpful.  You  can  even  remove 
your  listings  with  facebook. marketplace .  removeListing.  Furthermore, 
if  you  want  your  application  to  be  able  to  search  within  certain  specific  categories, 
the  API  provides  you  facebook. marketplace. getCategor ies  and 
facebook .marketplace . getSubCategories  methods. 

Notes  API 

Facebook  lets  your  application  create,  edit  and  delete  rich  text  documents 
called  Notes  if  it  has  been  granted  special  permissions.  We  will  cover  this  is 
more  detail  in  a  subsequent  section. 

Notifications  API 

With  its  REST  API  calls,  Facebook  allows  you  to  send  and  receive  notifications  in 
your  application.  To  get  your  user's  request  notifications  and  to  see  outstanding 
notification  responses,  use  the  facebook.notifications.get  method.  To  send 
notifications  to  your  users,  use  the  facebook.notifications.send  method  and  to 
send  invitations  to  them,  use  the  facebook.notifications.sendRequest  method. 

Messaging  API 

Messaging  API  contains  the  API  methods  that  allow  applications  to  send 
Facebook  notifications  and  email  (with  the  help  of  the  Notification  API), 
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update  users'  Facebook  status  (with  the  help  of  the  Status  API),  and  send 
Live  Messages,  i.e.,  messages  sent  to  a  particular  user's  browser  via  FBJS 
that  are  extremely  useful  in  applications  that  have  sequential  or  turn-based 
semantics,  such  as  games. 

Pages  API 

Pages  API  contains  methods  that  allow  developers  to  get  specific  information 
about  Facebook  Public  Profiles  or  previously  known  as  Facebook  Pages. 
They  return  information  about  whether  a  logged- in  user  is  the  administrator 
of  the  Public  Profile,  if  he/she  is  a  Fan,  and  whether  a  specific  application  has 
been  added  to  the  profile. 

Photo  and  Video  API 

Facebook  is  one  of  the  largest  photo  and  video  sharing  web  site  on  the 
web.  More  than  60  million  images  are  added  every  week  by  its  users.  To 
handle  these,  Facebook  provides  a  set  of  APIs  for  developers  to  manage  and 
interact  with  these  assets  from  within  their  applications.  These  methods 
and  functions  allow  users  to  upload,  create  albums,  and  retrieve  tagged 
user  information,  among  other  things.  Images  can  be  tagged  with  the 
facebook .  photos  .  addTag  method.  Photo  albums  can  be  created  by  using 
the  facebook. photos .  createAlbum  method.  To  get  a  user's  individual 
photos,  use  the  facebook.  photos  .get  method  and  for  a  listing  of  their 
albums,  use  the  facebook .  photos  .  getAlbums  method.  The  listing  of  the 
tags  that  individual  photos  have  can  also  be  obtained  with  the  facebook. 
photo .  getTags  method.  You  can  also  upload  photos  with  the  method 
facebook. photos. upload.  Many  of  these  methods  require  extended 
permissions  for  applications  to  use  them. 

Profile  API 

The  profile  API  contains  methods  to  easily  interact  with  setting  information 
in  the  user's  profile  and  manage  users'  application  profile  boxes,  application 
tabs,  or  info  sections.  The  two  methods  you  will  be  using  as  part  of  this  are 

facebook. prof ile . setFBML  and  facebook .prof ile . getFBML. 

Open  Stream  API 

With  Facebook's  real-time  streaming  update  model,  publishing  content 
to  the  stream  is  currently  a  somewhat  complex  and  detailed  process.  The 
new  Open  Stream  API  provides  a  new  way  for  applications  to  access  the 
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Feed  than  what's  provided  normally.  It  even  lets  you  access  the  stream,  read 
content  from  the  stream,  publish  your  own  content,  and  manage  comments 
and  ratings  for  individual  Feed  stories  from  outside  Facebook,  whether  it  be 
on  an  external  web  site,  a  mobile  application,  or  a  desktop  application. 

2.2  Test  console 

You  can  learn  a  lot  about  the  API's  functionality  by  using  the  Facebook  API 
Test  Console.  Go  to  the  URL  http://developers.facebook.com  to  access  the  Facebook 
developers'  section  in  your  browser.  Click  on  the  link  to  the  Tools  page  or  go 
directly  to  http://developers.facebook.com/tools.php. 

The  API  Test  Console  has  a  number  of  felds: 

User  ID  -  A  read-only  field  which  displays  your  user  ID  number. 
Response  Format  -  This  is  used  to  select  the  type  of  response  that  you  want: 

•  XML 

•  JSON 

•  Facebook  PHP  Client 

•  Callback  -  With  this,  you  can  encapsulate  the  response  in  a  function  if  you 
are  using  XML  or  JSON. 

•  Method  -  To  insert  the  actual  Facebook  method  that  you  want  to  test. 

•  The  Test  Console  also  has  the  documentation  link  which  is  used  to  select 
a  method  from  the  drop-down  list,  and  view  its  documentation  which 
consists  of: 

•  A  description  of  the  method 

•  The  parameters  used  by  the  method 

•  An  example  return  XML 

•  A  description  of  the  expected  response. 

•  The  FQL  equivalent 

•  Error  codes 

API  Essentials 

API  calls  are  your  first  interaction  points  with  the  platform.  You  don't  need 
to  use  the  client  library;  but  it  just  makes  things  easier  since  you  would  need 
to  write  these  in  your  language  in  order  to  interact  with  the  platform. 

To  set  up  the  client  library  for  PHP,  just  include  the  client  library  in 
your  code. 

For  example,  the  code  to  make  sure  that  users  are  logged  on  to  Facebook 
before  displaying  a  list  of  the  user's  friends  goes  like: 
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<?php 

$f acebook_config [' debug ' ]   =  false; 
$facebook  config['api  key']   =   '<your  api  key>'; 
$facebook  config [' secret  key']   =   '<your  secret  key> ' ; 
require  once('<path  to  client  library>/f acebook.php ' ) ; 
$ facebook  =  new  Facebook ($facebook_conf ig [' api_key '] , 
$f acebook_conf ig [ ' secret ' ] )  ; 
$user  =  $f acebook->require  login (); 
$friends  =  $f acebook->api  client->f riends  get(); 
echo    "<pre>Friends : "     .     print  r($friends,     true).  "</ 
pre>" ; 
?> 

Here,  you're  just  throwing  the  results  from  the  friends  object  on  the 
screen.  The  syntax  for  interacting  with  the  API  is  abstracted  into  methods 
of  the  API  in  the  Facebook  object.  This  code  requires  the  user  to  be  logged 
on  to  Facebook  in  order  to  execute.  The  require  login  ( )  method  is  used 
to  store  the  user's  identification  number  (UID)  in  the  variable  user.  The 
next  call  wrapped  it  in  the  PHP  method  friends  get  queries  the  Facebook 
API  method  friends.get.  There's  no  need  to  pass  the  UID  to  the  API  request 
because  the  facebook  object  holds  the  user's  identification  number  (their 
primary  key  or  UID).  The  PHP  code  here  actually  sets  up  a  REST  client  to 
call  the  facebook .  friends  .  get  API  method  and  returns  an  array  of  user 
identifiers: 

public  function  f riends_get ( )  { 

if    (isset  ($this->f riends_list) )  { 

return  $this->f riends  list; 

} 

return  $this->call_method ( 'facebook. friends. get'  , 
array ( ) ) ; H 
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Facebook  provides  official  support  for  the  following  libraries: 

•  PHP  5  -  use  the  subversion-command  svn  checkout  http:  //svn  . 
facebook.com/svnroot/platform/clients/php/trunk/.  It  is  the 
most  widely  used  library  by  developers.  Most  books  and  Developer  forum 
posts  reference  the  use  of  this  library. 

•  JavaScript  Client  Library  -  Although  it's  not  as  complete  as  the  PHP 
library,  it  forms  the  basis  of  Facebook  Connect  and  will  be  expanded  as  time 
goes  on. 

•  Facebook  Connect  for  iPhone  -  http://www.github.com/facebook/facebook~iphone- 
sdk.  It  is  written  in  Objective  C,  which  is  the  iPhone's  primary  development 
language.  This  library  provides  services  and  methods  to  make  it  easier  for 
iPhone  developers  to  allow  their  applications  to  connect  to  Facebook  from 
the  iPhone. 

•  ActionScript  3.0  Library  for  Facebook  Platform  -  http://www.adobe.com/go/ 
facebooklibrary.  It  is  officially  supported  by  Adobe.  This  library  allows  Adobe 
Flash,  Flex,  and  Air  applications  to  directly  refer  and  call  the  Facebook  API. 

•  Microsoft  SDK  for  Facebook  Platform  -  http://www.microsoft.com/facebooksdk. 
This  is  officially  supported  by  Microsoft. 

•  Force.com  for  Facebook  -  It  is  officially  supported  by  salesforce.com.  This 
library  allows  developers  on  the  Salesforce  platform  to  integrate  Facebook 
into  their  custom  Sales  force  platform  applications. 

Unofficial  Libraries 

The  Facebook  Platform  developer  community  maintains  the  following  client 
libraries.  Facebook  does  not  provide  official  support  for  them.  Many  of  them 
are  active,  but  some  are  just  a  proof  of  concept. 

•  Android 

•  FBFlashBridge 

•  ASP.NET 

•  ASP.NET  MVC 

•  ASP  (VBScript) 

•  ASP(JScript) 

•  Cocoa 

•  ColdFusion  -  See  also  Developing  a  ColdFusion  Application  in  8  Minutes 

•  C++ 
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•  c# 

•  D 

•  Emacs  Lisp 

•  Erlang 

•  Google  Web  Toolkit 

•  Haskell 

•  Java 

•  Kontagent  pre-instrumented  libraries  -  Provides  Instant  to  Kontagent 
Social  Analytics  without  additional  work 

•  PHP  -  with  Kontagent  Analytics  -  Pre-instrumented  with  Kontagent  -  a 
fbFund  Company 

•  Ruby  on  Rails  -  with  Kontagent  Analytics  -  Pre-instrumented  with 
Kontagent  -  a  fbFund  Company 

•  Facebook  Connect  for  Web  with  Kontagent  Analytics  -  Pre-instrumented 
with  Kontagent  -  In  Beta 

•  Facebook  Connect  for  iPhone  with  Kontagent  Analytics  -  Pre- 
instrumented  with  Kontagent  -  In  Beta 

•  Lisp  (Common  Lisp)  -  seems  to  run  only  with  SBCL 

•  Perl 

•  Python 

•  Ruby 

•  Ruby  MiniFB  gem  -  a  tiny,  simple  to  use  Ruby  library  for  Facebook 

•  Ruby  on  Rails 

•  Smalltalk 

•  Tel 

•  VB.NET 

•  Windows  Mobile/Facebook  Development  with  the  .NET  Compact 
Framework 

•  zembly,  allows  executions  within  zembly  and  external  invocations  from 
Java,  JavaFx,  and  PHP 

Facebook  updates  its  libraries  frequently,  but  these  changes  are  generally 
always  preannounced  on  the  developer  blog.  In  these  changes,  API  methods 
are  often  deprecated  but  they  still  function  correctly  until  a  cutoff  date. 
This  means  that  older  applications  do  not  necessarily  have  to  be  updated  or 
rewritten  to  always  use  the  latest  version  of  the  library. 

Client  Library  Essentials 

We  shall  be  using  the  PHP  library  throughout  the  Facebook.  If  you're 


FAST  TRACK -APRIt  2010 


24 


thinkd\9\t 


Creating  Facebook  Apps 


Official  Libraries  El 


planning  on  working  with  some  other  language,  most  of  the  concepts  will  be 
the  same,  but  depending  on  how  the  developer  who  wrote  the  library  chose 
to  implement  the  elements  and  the  characteristics  of  the  Facebook  API,  the 
way  methods  are  called  and  named  might  be  slightly  different.  Also,  some 
libraries  are  better  documented  than  others;  but  in  case  you  run  into  a 
problem  and  you  can't  get  help  with  your  language-specific  version,  take  a 
look  at  the  documentation  for  the  "official"  client  libraries  for  PHP  or  Java. 

Facebook's  PHP  library  consists  of  two  main  object  classes,  Facebook 
(facebook .  php)  and  Facebook  Rest  Client  (f  acebookapi_php5_ 
rest  lib.  php).  The  Facebook  Rest  Client  class  abstracts  interactions  with 
Facebook's  API.  The  Facebook  class  just  utilises  the  FacebookRestClient 
class's  methods  to  further  abstract  common  interactions  with  the  Facebook 
platform.  For  instance,  instead  of  writing  a  function  to  require  a  user  to 
have  a  session  key  to  work  with  your  application,  the  Facebook  object  has  a 
method  called  require  login  ( )  that  checks  for  the  session  key  and,  if  it 
doesn't  find  one,  redirects  the  user  to  Facebook  to  perform  the  authentication 
on  the  login  page  and  then  returns  the  user  to  your  application. 

Example  usage: 

<?php 

require  once ( ' <client  library>/ facebook. php ') ; 
$secret  key  =   '<secret  key>'; 
$api  key  =  '<apikey>'; 

$facebook  =  new  Facebook ($api_key,    $secret_key) ; 
?> 

The  API  and  secret  keys  are  assigned  to  you  in  your  My  Applications 
portion  of  Facebook's  Developer  application  (http://www.facebook.com/developers/ 
apps.php).  Once  instantiated,  the  Facebook  client  libraries  make  it  easy  for  your 
application  to  interact  with  the  Facebook  platform. 

When  you  create  a  Facebook  object,  that  class  includes  a  library  to  make 
the  REST  calls  (facebookapi_php5_restlib.php).  If  you're  using  PHP 
to  write  a  desktop  application,  you  need  to  use  the  facebook  desktop . 
php  file,  which  extends  the  Facebook  object  but  is  better  suited  to  desktop 
applications.  The  f acebookapi_php5_restlib .  php  file  is  where  you  will 
find  most  of  the  functions  you  will  use  in  your  application  and  thus  is  the 
real  workhorse  for  your  application. 

Let's  take  an  example  to  see  how  all  the  different  parts  and  components 
of  the  program  work  together  with  the  platform.  This  sample  application 
allows  users  to  set  their  status  using  the  PHP  client  library,  the  Facebook 
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API,  FQL,  mock  Ajax,  and  FBML.  Create  an  index.php  file  in  the  Facebook 
folder  of  your  web  server  and  use  the  following  source  code: 

<?php 

$f acebook_conf ig [' debug ' ]   =  false; 

$facebook  config [' secret  key']   =   '<secret  key> ' ; 

$ facebook  config ['api  key']   =   '<api  key> ' ; 

require  once ( ' <client  library>/f acebook.php ' ) ; 

$facebook  =  new  Facebook ($facebook  config['api  key'], 

$f acebook_conf ig [ ' secret ' ] ) ; 

$user  =  $f acebook->require  login (); 

?> 

This  sets  up  the  constants  (api  key  and  secret  key)  and  instantiates  a 
Facebook  object  (which  includes  an  instance  of  the  API  REST  client).  To  add 
functionality  to  the  application,  use  the  following  code  block: 

<div  style="padding: 5px; "> 

<hl>Hello 

<fb:name      uid="<?=      $user?>"       f irstnameonly="true" 
capitalize="true"  /> 
</hl> 

<p>What's  your  new  status?</p> 
<f orm> 

<input  type="text"  name=" status"  value="conf used"  /> 
<input  type=" submit" 
clickrewriteid="curr  status" 
clickrewriteurl="<callback  url>"  /> 
</f orm> 

<div  id="curr  status"x/div> 
</div> 

The  user  variable  you  set  in  the  PHP  code  is  used  to  display  the  user 
name.  We've  also  created  a  mock  Ajax  call  to  populate  the  empty  preview  div. 
Code  to  handle  updating  the  status  goes  like: 

if (isset ($_REQUEST[ 'status ' ] ) ) 

{ 

$has  permission  = 

$ f acebook->api  client->call  method (" facebook . user s . 
hasAppPermission" , 

array ( "ext_perm"=>" status_update" ) ) ; 
if($has  permission)} 
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$  f acebook->api_cl ient->call_method ("facebook. users. 
setStatus" , 

array ("status"  =>  $_REQUEST [' status ']))  ; 

$fql  =  "SELECT  status  FROM  user  WHERE  uid="    .  $user; 

$query_result  =  $f acebook->api_client->fql_query ($fql)  ; 

$status  =  $query_result [0 ][' status '][ 'message ']  ; 

echo ( "<p>Your  new  status  is:  <strong>"  .  $status  .  "</ 
strong></p>") ; 

}   else  { 

$url  =  '<a  href ="http : //www . facebook . com/ authorize . 
php  ?  ap  i  ke  y  = '  ; 

$url  +=  $api_key  .  ' &v=l . 0 &ext_perm=status_update">Click 
here</ a> ' ; 

echo('<p  style="f ont-size : 14px; ">  '); 

echo ( ' D\ ' It  doesn\'t  look  like  you  have  the  permissions 
to  change  yourstatus.  '  .  $url  .  '  to  add  the  permissions 
to  update  yourstatus.'); 

echo ( '</p> ' ) ; 

} 

exit; 
} 

What  we  are  basically  doing  is  first  checking  the  permissions  for  the  user 
because  updating  the  user's  status  requires  additional  permissions  and  if 
the  user  has  permission,  updating  the  status  using  an  APIcall,  and  then  you 
querying  Facebook  with  FQL  to  make  sure  that  the  status  you  just  set  is  in 
fact  the  current  status.  Next  we  are  displaying  it  within  the  currjstatus  div. 
The  source  code  becomes: 

<?php 

$f acebook_conf ig [' debug ' ]   =  false; 

$facebook  config [' secret  key']   =   '<secret  key> ' ; 

$ facebook  config ['api  key']   =   '<api  key> ' ; 

require  once ( ' <client  library>/f acebook.php ' ) ; 

$ facebook  =  new  Facebook ($facebook_conf ig [' api_key ']  , 

$f acebook_conf ig [ ' secret ' ] ) ; 

$user  =  $f acebook->require  login (); 

if (isset ($_REQUEST[ 'status ' ] ) ) { 

$has  permission  =  $f acebook->api  client->call  method ( 
"facebook. users . hasAppPermission" , 


thinkd\9\t 


27 


FAST  TRACK-  APRIL  2010 


D  Official  Libraries 


Creating  Facebook  Apps 


array ( "ext_perm"=>"status_update" ) 
)  ; 

if($has  permission) { 

$f acebook->api_client->call_method ( 

" facebook . user s . setStatus" ,       array  (" status"      =>  $_ 
REQUEST [ 'status ' ] ) 
)  ; 

$fql  =  "SELECT  status  FROM  user  WHERE  uid="    .  $user; 
$query_result  =  $f acebook->api_client->fql_query ($fql) ; 
$status  =  $query_result [0 ][' status '][ 'message ']  ; 
echo ( "<p>Your  new  status  now:  <strong>"   .   $status   .  "</ 
strong></p>") ; 
}else  { 

$url  =  '<a  href ="http : //www . facebook . com/ authorize . 
php  ?  ap  i  ke  y = ' ; 

$url  +=  $api_key  .  ' &v=l . 0 &ext_perm=status_update">Click 
here</ a> ' ; 

echo('<p  style="f ont-size : 14px; ">  '); 

echo ( ' D\ ' It  doesn\'t  look  like  you  have  the  permissions 
to  change  yourstatus.  '  .  $url  .  '  to  add  the  permissions 
to  update  yourstatus.'); 

echo ( '</p> ' ) ; 

} 

exit; 
} 

?> 

<div  style="padding: 5px; "> 

<hl> 

Hello 

<fb:name      uid="<?=      $user?>"       f irstnameonly="true" 
capitalize="true"  /> 
</hl> 

<p>What's  your  new  status?</p> 
<f orm> 

<input  type="text"  name=" status"  value="conf used"  /> 
<input  type="submit"  clickrewriteid="curr  status" 
clickrewriteurl="<callbackurl>"  /> 
</f orm> 
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<div  id="curr_status"x/div> 
</div> 

The  Facebook  platform  has  lots  of  quirks  since  the  code  you  write  is 
interpreted  through  Facebook.  Whenever  you  create  a  new  form,  Facebook 
creates  several  additional  input  fields  in  your  form,  which  are  used  by 
Facebook  to  process  your  input.  Another  thing  to  keep  in  mind  is  that  FBML 
isn't  HTML.  Although  you  can  use  most  of  the  familiar  tags  in  FBML  as  you 
do  in  HTML,  there  are  differences  in  the  way  in  which  tags  are  processed. 
Your  ability  to  use  external  CSS  files  for  your  application  is  also  limited.  You 
can  only  embed  your  CSS  in  the  page  using  the  <style>  tag.  Generally  it 
isn't  a  big  deal  if  you  have  a  small  application,  but  as  your  application  grows 
in  size  and  usage,  this  becomes  less  manageable.  An  alternative  to  this  is  to 
"fake"  the  style.  Instead  of  using  the  <link>  tag  to  point  to  your  style  file(s) 
like  you  do  in  HTML,  you  can  create  your  style  file  as  you  normally  would 
and  include  it  within  <style>  tags  in  your  PHP  code. 

Example: 

<style> 

<?php  require ( "style . ess"  )  ?> 
</style> 

This  code  snippet  will  effectively  include  the  style  sheets  for  your 
application.  You  can  also  use  the  <fb:ref>  tag  to  pull  the  entire  style 
sheet.  Facebook  also  prepends  your  application  key  to  the  variables.  The 
best  choice  for  all  this,  of  course,  depends  on  the  nature  of  your  application, 
environment,  and  what  you  want  to  code  with.  0 
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Digit's  Facebook  Apps  contest  by  going  to 

www.thinkdigit.com/d/fb_contest 


□  The  Basics 


Before  we  get  to  the  basics  of  creating  and  configuring  a  Facebook  application, 
we  need  to  set  up  a  developer  environment,  learn  about  the  basic  PHP 
skeleton,  Facebook  Markup  Language  (FBML)  and  the  official  PHP  client- 
libraries.  We  also  need  some  information  about  application  authorisation 
and  authentication,  Facebook  sessions  and  signatures  and  the  configuration 
settings  of  the  Facebook  Developer  application. 

4.1  Setting  a  developer  environment 

Facebook  provides  the  official  PHP  client  libraries  that  you  can  download 
from  its  source  code  repository  http://svn.facebook.com/svnroot/platform/clients/packages/ 
facebook-platform.tar.gz  and  extract  using  any  archiving  tool  such  as  WinRAR. 
Facebook  officially  supports  PHP  and  Java  client  libraries,  and  ASP.net 
by  its  collaborated  project  with  Microsoft  -  http://www.codeplex.com/FacebookToolkit. 
The  unofficial  libraries  of  several  other  programming  languages  can  also 
be  found  on  the  Facebook  Developers  Wiki  http://wiki.developers.facebook.com. 
This  shall  be  your  first  step  towards  making  a  Facebook  app.  This  client 
library  contains  all  the  resources  required  for  your  application  to  connect 
to  the  Facebook  platform,  encapsulate  the  standard  application  behaviour 
and  access  the  API  functions  using  PHP.  It  is  nothing,  but  a  set  of  three 
files  namely, 

•  facebook  api  restlib.php  -  It  lets  you  implement  the  FacebookRestClient 
class  that  provides  raw  HTTP  access  to  the  Facebook  REST  API. 

•  facebook.php  -  It  lets  you  implement  standard  Facebook  web-application 
behaviour  in  your  application. 

•  facebook  desktop.php  -  It  lets  you  implement  standard  Facebook  desktop- 
application  behaviour  in  your  application. 


Quick  Start 

Sometimes  its  easier  to  learn  by  seeing  something  in  action ,  Tliat  is  why  we've  provided  you  with  a  sample  application  you  can  dive  right  into . 

Qj  Download  the  Client  Library  More  Helpful  Links 

This  package  has  all  the  hies  that  make  up  the  official  PHP  Client  Platform  Documentation 

Library,  as  well  as  a  sample  application.  Anatomy  of  a  Facebook  Apprication 

Code  Samples 

Test  Console  (API,  FBML,  Feed) 
Unofficial  Client  Libraries 


Download  the  client  libraries  from  the  same  application  summary  page 
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Including  any  of  facebook.php  and  facebook_desktop.php  enables  your 
PHP  application  to  direcly  access  the  Facebook  API. 

Once  you've  the  client  libraries,  you  need  to  set  up  a  web  server  to  host  any 
application  that  you  create.  You  can  either  host  it  locally  or  on  a  web-based 
company  that  provides  hosting  space  (There  are  many  free  solutions,  but  we 
recommend  you  try  one  of  the  paid  servers  for  more  security  and  reliability). 
You  need  to  follow  these  steps  to  get  your  application  up  and  running: 

Before  you  actually  start  writing  your  application,  you  need  to  register 
your  application  with  Facebook  and  get  some  application-specific 
information  that  will  be  essential  for  your  application  to  communicate  with 
the  Facebook  platform.  By  this,  we  mean  the  API  key  and  the  secret  key  that 
needs  to  be  specified  in  your  code. 

Log  into  your  Facebook  account  and  go  to  www.facebook.com/developers  add  the 
application  to  your  Facebook  profile.  On  the  top  right  corner,  you  will  see  the 
"Set  up  New  Application"  button.  Click  on  it.  Give  your  application  a  name 
that  helps  other  people  identify  it,  agree  to  Facebook  Terms  and  Conditions 
and  click  on  save  changes. 

Now  the  basic  stuff  is  in  place,  so  let  us  associate  a  logo  with  this 
application.  This  just  makes  it  easy  for  people  to  recognise  your  application. 
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S  Create  Application  Back  b  My  Appiic; 


Essential  In  formation 

Application  fame           ni™fTp<=t  Arm  Cannot  contain  Farebook 

"BP   ■---  ■  -■-^    nadanaris  or  r^  a  name 


Do  you  agree  to  the  Facebook  Terms? 
Agree    Q  Disagree 


Create  Application 


Enter  the  desired  name  for  your  application 


Let  us  also  add  a  description  because  then  it  becomes  easy  for  people  to  find 
your  application  through  the  Facebook  application  directory.  You  can  also 
add  an  email  address  that  people  can  use  for  technical  support. 

B  Edit  Digit  Test  App  Back  to  My  Applications 


Authentication 

Profiles 

Connect 
Widgets 
Advanced 


Canvas  Page  UR1        http://appg.facebook.com/  digits 


Canvas  Callback  URL 


Optional  URLs 
Post- Authorize  Redirect 


■"■rb:  r,v,—dc  t>:-:eL"'00^_iss;_f. 


blink,  the  f  ekr  detail 
Canvas  Page  URL, 


Render  Method         Q  IFrame     Mi  FBML 


Canvas  Width  a  Full  width  (76Gpx)  8  Old  width  [6*px) 
quick  Transitions        <~j  Op     □  off 


of  the  Fsjsltok  frjm: 


The  canvas  page  of  settings 

Then  head  over  straight  to  the  canvas  tab.  There  you  will  see  render 
methods.  You  have  to  choose  between  iFrame  and  FBLM.  For  this  example 
to  be  simple,  we  will  use  FBML.  Choose  it  and  click  on  save  changes.  You  also 
need  to  populate  the  base  and  callback  URL  for  your  application.  Base  URL 
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Application  Type         @  web     ©  iDesktop 

Sandbox  Mode         Q  Enable     @  Disable 

Lets  only  iflie  developers  of  your 

application  see  it 

SMS  Integration         Q  Enable     @  Disable 

Let  you  integrate  yoir  apf&caftxh 

iPhone  Application  ID 

If  you  lave  an  iPhcne  app  using 

Connect,  fiH  tfcs  in  with  yew  Apple- 

so;  :=:'or  ID. 

Set-up  the  application  type  to  web 

Authentication 

Connect 
Widgets 
Advanced 


7a  b  Na  nie 
Tab  URL 


Default  Column 
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appeare,  User?  —  =  --. 
dse  inhere  on  die  profile, 


The  profiles  tab 

is  the  just  the  fancy 
URL  name  that  other 
people  will  be  using  to 
access  your  application 
page.  Facebook  will 
provide  immediate 
feedback  if  that  url  is 
unavailable,  in  which 
case  you  should  pick 
something  else.  The 
callback  URL  is  the 
actual  stuff  that  points 
to  the  application  to 
your  server.  Make  sure 
you  enter  the  URL  of 
the  folder  in  which  your 
index.php  and  other 
pages  are  located  and 
not  the  actual  index, 
php  URL. 
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Next  head  over  the  Advanced  settings  option.  Select  web  site  for  this 
example  as  we  will  be  creating  a  traditional  web  app  that  integrates  with 
Facebook  and  not  a  desktop  app  which  accesses  Facebook  using  the  API  and 
is  run  like  a  normal  desktop  application. 

Now  go  the  Authentication  Options  tab.  Here  you  can  select  who  all 
can  add  your  application  to  their  Facebook  account.  Specify  a  URL  in  the 
PostAuthorise  callback  URL  text  box.  It  is  the  URL  that  the  Facebook 
sends  a  notification  to,  once  a  user  authorizes  your  application.  Select  the 
wide  option  in  the  Default  Profile  Box  column  for  a  rich  experience.  Also 
fill  in  the  URL  that  you  want  users  to  get  redirected  to  after  installing 
your  application  in  the  Post-Authorise  redirect  URL  on  the  Canvas  page. 
Make  it  your  canvas  URL,  basically  the  URL  you  typed  in  the  base  URL 
field  earlier. 

Finally  Click  the  Submit  button.  You  will  be  taken  to  the  My  Applications 
page  where  you  will  get  access  to  your  API  key  and  the  secret  key  along  with 
other  meta  information  about  your  application. 

4.1.1  Creating  your  Facebook  Application 

Now  that  you  have  your  API  and  secret  key,  you  are  ready  to  create  an 
application  using  the  Facebook  client  library.  We  are  more  or  less  done  on 
the  Facebook  site  as  of  now.  You  need  to  uncompress  the  downloaded  file 
and  copy  the  client  file  libraries  in  the  folder  that  you  specified  as  your 
canvas  URL  while  setting  up  your  application.  The  PHP  client  library 
that  we  will  be  using  is  under  the  main  folder  named  Facebook-platform. 
Next  you  need  to  create  a  new  file  named  appinclude.php.  You  can  use 
Dreamviewer  to  do  this  or  even  simple  text  editing  softwares  such  as 
Notepad.  This  file  will  contain  the  Facebook  initialization  code  required 
by  your  application  to  connect  to  the  Facebook  platform.  You  will  have  to 
include  this  file  in  all  other  PHP  files  in  your  application  because  this  will 
contain  your  API  key,  secret  key  and  callback  URL.  Type  out  the  following 
code  in  this  file: 
<?php 

require  once  ' . . /f acebook-platf orm/client/f acebook . 
php'  ; 

$appapikey  =   '  [api_key] ' ; 
$appsecret  =   '  [secret_key] ' ; 
$appcallbackurl  =   ' [web_app_callbackurl]  '  ; 
$facebook  =  new  Facebook ($appapikey,    $appsecret) ; 
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$user  =  $f acebook->require_login ( ) ; 
try  { 

if    (  ! $f acebook->api_client->users_isAppAdded ( ) )  { 
$f acebook->redirect ($f acebook->get_add_url ()  )  ; 
} 

}   catch   (Exception  $ex)  { 
$facebook->set_user (null,   null) ; 
$f acebook->redirect ($appcallbackurl) ; 
} 

?> 

Replace  the  API  key,  secret  key  and  the  callback  URL  wherever  required. 

Next  log  on  to  your  webserver  (your  callback  URL,  remember?)  and  create 
a  folder  for  your  application.  This  is  required  because  the  facebook.php  path 
in  the  require_once  statement  of  the  appinclude.php  file  we  just  wrote  requires 
your  app  files  to  be  located  in  a  separate  parallel  folder  with  the  Facebook 
client  libraries.  This  step  is  flexible  as  you  can  change  the  path  of  facebook.php 
in  appinclude.php  if  your  folder  structure  differs.  You  are  now  ready  to  write 
index.php  of  your  application.  The  necessary  code  in  that  file  has  to  be 

<hl>  Digit  Test  Application</hl> 

<?php 

require  once  'appinclude.php'; 

?> 

These  are  basically  the  title  of  your  application,  the  PHP  start  and  end 
tags  and  a  require_once  statement  to  include  appinclude.php  file. 

You  can  play  around  this  page  as  you  desire.  Let  us  make  our  application 
display  the  user's  name.  For  this,  you  need  to  type  in  the  following  php  code 
in  your  index.php  after  the  necessary  code  echo  "<p>Your  user  name 
is:   <fb:name  uid=\"$user\"  useyou=\"f alse\"/x/p>"; 

We  are  basically  using  the  f  b :  name  FBML  tag  to  render  the  name  of  the 
current  user.  If  you  want  to  add  a  list  of  your  Facebook  friends,  you  can  do 
this  by  the  following  code  in  your  index.php: 

echo  "<p>Your  friends:  </p>"; 

$friends  =  $f acebook->api  client->f riends  get(); 
echo  "<ul>"; 

foreach   ($friends  as  $friend)  { 

echo     "<lixfb:name     uid=\"$f  riend\"     useyou=\"f  alse\" 
/></li>"; 
} 
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echo  "</ul>"; 

To  try  out  this  application,  save  the  file,  and  copy  it  into  your  application 
folder  on  your  web  server.  Next  enter  the  canvas  page  URL  of  your  application 
after  making  sure  you  are  logged  into  Facebook  in  your  web-browser.  You  will 
be  redirected  to  your  callback  URL  and  the  index.php  will  be  rendered  back 
inside  the  Facebook  canvas.  There's  a  lot  more  you  can  do  with  your  application. 


4.1.2  Add  an  Icon  to  your  application 

You  would  probably  want  an  icon  to  be  displayed  along-side  the  application 
name.  This  is  fairly  simple.  Just  go  back  to  www.facebook.com/developers,  and  click 


Documentation     Forum  Policy 

Help 

H  Upload  an  Icon 

+  Set  Up  N 

w  Application  ) 

You  can  upload  a  ]PG,  GIF,  or  PNG  file.  If  the  image  is  larger  than  16x16  pixels 
be  resized  and  converted. 

rt  wi  1 1 

C:\Users\Anot\Pictures\lmag<  |  Browse.  | 

[7;  I  certify  that  I  have  the  right  to  distribute  this 
photo  and  that  it  is  not  pornography. 

|     Cancel  | 

Ffe  size  limit  5  M  B.  If  your  upload  Axs  not  wok,  try  a  smaller  picture. 

Uploading  an  icon  for  your  application 


on  See  My  Apps  button  in  the  My  applications  box.  Next,  click  on  Edit 
settings.  The  base  settings  page  will  open.  Here  click  on  your  icon  link, 
and  then  on  the  Choose  file  button.  Locate  an  image  on  your  HDD,  select 
the  certification  box  and  click  on  upload.  Facebook  will  automatically  render  it 
and  fit  the  required  size.  All  you  need  to  do  now  is  click  on  save  and  you  are  done. 

4.1.3  Add  content  to  the  Profile  box  of  your  application 

You  probably  want  your  application  to  have  some  content  when  it  appears 
as  a  box  of  the  profile  page.  To  set  this  up,  all  you  need  to  do  is  add  some  code 
to  the  index.php  file  just  after  the  require_once  'appinclude.php'  statement. 

$def ault_text  =  "<p>Hey,  <fb:name  uid=\"$user\" 
useyou=\"f alse\"  />!  This  Digit  test  Application  is 
part  of  a  sample  guide  to  creating  your  own  Facebook 
applications . </p>"  ; 

$f acebook->api_client->prof ile_setFBML ($def ault_text)  ; 
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H  Edit  Digit  Test  App  Application 


Infornia  tion 

News  for  Page  Admins 

if  Application  Information 

Edit 

Fan  Badges  -  Have  your  fens 
show  their  support  to  their 
friends 
4:10am  Dec  IS 

[|r~|  Use  your  Mobile  Phone  to 

publish  to  fans! 

ldfUarDetlS 
HfZ|  New:  Publish  to  Fans  Based  on 

Location  and  Language 

12:Clpm  Nov  19 

Edit  application  description^  category,  and  develops-  anqsan  f  -  formation, 

5jj  Application  Settings 

Edit 

Edit  and  configure  trie  settings  for  your  application, 

Q  Wall  Settings 

Edit 

See  More  Mews 

Change  the  default  view  for  fans  and  control  who  can  post  to  your  Wall. 

Insights 

£  Mobile 

—  Total  Fans 

Edit  ■  Learn  more 

Page  Activity* 

Publish  status  updates,  photos  and  videos  to  your  Facebook  Page  on  trie  go. 

No  Data  to  Display 

Applications 

*  Available  48  Hoirs  After  Activity 

,— ,  Discussion  Boards 

Edit '  Application  Settings  Link  to  this  Tab  ■  Remove  Application 

All  Page  Insights 

Promote  your  page 

Discussion  boards  enable  your  fans  to  get  their  ideas  out  into  the  open ,  Discussion  boards  let  you  know 
exactly  what  your  fans  and  customers  think  and  want.  Get  the  conversation  started  now! 

Promotion  Guidelines 

[~]  Reviews 

Application  Settings  ■  Link  to  this  Tab 

^  Promote  with  a  Fan  Box 

With  reviews,  your  fans  and  cue  torre1  ■:■       e*  e  honest  opinions  about  yourbusiness.  Reviews  lets  your 
prospective  fans  know  what  to  expect  with  you, and  can  influence  people  interacting  with  your  business. 

Developers  Add 

P*^feaW  RahilBanthia 

@  More  Applications 

Browse  More 

Applications  you  might  find  useful: 

Video        [|T]  Events 
|g  Photos 

Help  with  Your  Page 

For  tips  and  information  about 
Facebook  Pages,  dick  here. 

Promote  with  Facebook 
Badge 

Get  Your  Badge 

You  can  change  almost  anything  about  your  application  from  the  Application  Profile  page 


4.1.4  Add  an  About  Page 

You  also  should  add  an  about  page  for  your  application  so  that  Facebook 
users  get  to  know  what  your  application  is  all  about.  Its  also  an  important 
marketing  step  while  you  are  promoting  your  application. 

Go  back  to  www.facebook.com/developers,  and  click  on  See  My  Apps  button  in  the 
My  applications  box.  Next,  click  on  Edit  Application  Profile.  Here  is  where 
you  can  also  modify  your  Application  name  and  the  description  which  you 
initially  gave  while  setting  up  your  application.  Add  up  all  that's  relevant  to 
your  application  and  click  on  Save. 
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4.1.5  Redirect  users 

In  case  you  want  to  redirect  Facebook  users  from  your  app  to  a  new  URL 
within  the  canvas  page,  you  can  use  the  fb:redirect  FBML  tag.  The  statement 
required  for  this  is- 

<fb: redirect  url="http : //thinkdigit . com/"  /> 


HTTP  Request  |  Mocahons  |  User  ftesponse  |  Features  |  Aj>pBcatk>n  Profile  | 


Ej  Past  Day  □  Past  7  Days  □  Past  30  Days 


4.1.6  Viewing  statics  about  your  application 

Once  you  are  done  setting  up  your  application  and  creating  it,  you  will  want 
to  view  some  statistics  about  it  and  how  users  are  reacting  to  it.  For  this,  go 
back  to  www.facebook.com/developers,  and  click  on  See  My  Apps  button 
in  the  My  applications  box.  Next,  click  on  stats.  The  application  stats  page 

will  appear  with 

o  insights:  Digit  Test  Aop  a[\  the  information 

regarding  how 
many  users  used 
your  application 
in  the  past  24 
hours,  total 
number  of  users 
who  have  added  it, 
number  of  users 
who  have  blocked 
or  removed  it  in 
the  past  24  hours, 
user  reviews  and 
a  summary  of 
sampled  HTTP 
requests  along 
with  their  return 
statuses. 


usage  statistics 

Month  lyActiveUsei 
Total  Users: 
Wall  Posts 
Reviews: 


Detailed  statistics  regarding  your  apps  usage 


4.1.7  Deleting  your  application 

If  you  are  not  satisfied  with  whatever  work  you  have  put  in  and  wish  to 
delete  your  application;  you  can  do  so  from  the  My  Applications  page.  This 
will  also  delete  the  API  key  generated  for  your  application. 

In  further  chapters,  we  will  get  into  the  finer  details  of  App  development 
and  build  the  canvas  page,  profile  boxes  and  give  your  application  the  ability 
to  handle  feeds,  notifications,  requests,  photos  and  other  multimedia.  H 
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What  you  learn  from  this  Fast  Track  could  win 
you  Rs.  20,000  in  exciting  prizes.  Take  part  in 
Digit's  Facebook  Apps  contest  by  going  to 

www.thinkdigit.com/d/fb_contest 


□  FBML  tags 


FBML  provides  a  large  set  of  Facebook  user  interface  and  programmatic 
primitives  required  to  abstract  complex  code  and  make  most  routine 
procedures  effortless.  The  tags  are  automatically  parsed  and  translated 
into  HTML,  CSS  (Cascading  Style  Sheets),  and  JavaScript  code  by  Facebook 
servers  when  a  request  for  an  application  page  that  contains  it  is  detected. 
If  you've  previously  used  HTML,  then  you  will  have  no  problems  adapting 
to  FBML.  To  distinguish  between  HTML  and  FBML  commands  in  your 
application  code,  you  need  to  prefix  FBML  tags  with  fb:  as  you  would  if  you 
were  using  multiple  DTDs/schemas  in  XHTML.  FBML  tags  act  differently 
in  different  locations.  For  example,  you  can  use  iframes  on  canvas  pages,  but 
you  cannot  use  the  same  iframe  on  the  code  in  the  profile  box  due  to  platform 
limitations.  Let  us  delve  deeper  into  some  well-known  FBML  tags. 

5.1  Conditionals 

FBML  contains  many  conditional  tests  besides  the  <fb:if>  tag  that  lets 
developers  cut  down  on  implementing  conditional  statements  in  their 
application.  The  basic  <f  b :  if  >  tag  is  used  like  : 

<fb:if  value="true"> 

<p>Welcome . </p> 

</fb: if> 

The  value  can  be  set  dynamically  using  the  programming  language 
you're  making  the  application  in.  Suppose  you  want  to  test  a  user's  ID  and 
show  a  customised  welcome  message,  you  can  write  code  like: 

<?php 

$user  =  $f acebook->require  login (); 

$test  =  false; 

if  ($user  =  9999999)  { 

$test  =  1; 

} 

?> 

<fb:if  value="<?php  echo ($test) ?>"> 

<p>This  is  a  customized  welcome  message.  Welcome  John</ 

P> 

<fb:else> 
<p>Welcome . </p> 
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</fb: if> 

You  can  you  use  the  <fb:if>/<fb:else>  conditional  constructs  in  many 
more  complex  ways,  as  you  will  realise  during  the  application  development 
process.  Fortunately,  to  reduce  code,  Facebook  provides  you  will  a  set  of  tags 
that  will  do  most  of  the  common  types  of  conditional  checking: 

•  <fb :  is-in-network>  -  test  if  a  UID  is  in  the  specified  network. 

•  <fb :  if-can-see>  test  if  the  logged-in  user  has  permissions  to  view  the 
specified  content.  This  is  used  to  implement  various  privacy  features  in  your 
applications. 

•  <fb :  if-can-see-photo>  -test  if  the  logged-in  user  has  permissions  to 
view  the  specified  photo. 

•  <fb :  if-is-app-user>  -  test  if  the  current  user  has  accepted  the  terms 
and  conditions  of  service  for  your  application. 

•  <fb :  if-is-f  riends-with-viewer>  test  if  the  user  specified  is  in  the 
friend  list  of  the  current  logged-in  user. 

•  <fb :  if-is-group-member>  -  test  if  the  current  user  is  a  member  of  the 
specified  group. 

•  <fb :  if-is-own-prof  ile>  -  test  if  the  viewer  is  the  owner  of  the  profile 
he/she  is  on  currently. 

•  <fb :  if-is-user>  -test  if  the  viewer  is  in  the  list  of  the  specified  users. 

•  <f  b :  if -user-has-added-app>  test  if  the  specified  user  has  added  and 
accepted  the  application  to  their  account. 

You  should  be  wondering  by  now  as  to  why  we  haven't  talked  about 
the  else  if  FBML  construct  yet?  It's  because,  there  is  none!  If  you  want  to 
perform  multiple  conditional  checks,  you  will  have  to  properly  nest  your  if 
statements.  Alternatively,  use  the  FBML's  switch  construct.  The  <fb:switch> 
FBML  tag  evaluates  a  set  of  FBML  tags  and  returns  the  tag  information  from 
the  first  tag  that  returns  something  other  than  an  empty  string.  For  example: 

<?php 

$user  =  $f acebook->require  login (); 

$test  =  false; 

if  ($user  =  9999999)  { 

$test  =  1; 

} 

?> 

<fb : switch> 

<fb:if  value="<?php  echo ($test) ?>"> 
<fb : switch> 
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<fb:profile-pic  uid="<?php  echo ($user) ?>"  /> 
<fb : def ault> Inner  def ault</fb : def ault> 
</fb: switch> 
</fb: if> 

<f b : def ault>Outer  Def ault</ f b : def ault> 
</fb: switch> 

5.2  User/Group  information 

FBML  tags  let  your  users  easily  interact  with  other  users  of  your  application. 
This  includes  handling  and  managing  user  and  group  information  -  an 
important  part  of  any  Facebook  application. 

•  <fb:name>  -  This  tag  returns  the  user  name  for  the  uid  passed  as  the 
parameter  to  the  tag.  It  even  has  some  customisable  features  and  additional 
logic  to  work  with  users  who  have  protected  their  profiles.  For  example,  You 
can  write  <fb: name  uid="$user"  if cantsee="Anonymous">  and  the 
tag  will  return  "Anonymous"  if  the  user  has  chosen  not  to  display  their  name 
in  their  profile. 

•  <fb :  grouplink>  -  This  tag  returns  the  name  and  the  link  of  the  group 
ID  passed  as  parameter  to  the  tag. 

•  <fb:user>  -  This  tag  is  used  to  displays  content  to  the  specified  user  and 
not  to  everyone  in  general. 

•  <f  b :  prof  ile-pic>  -  This  tag  renders  a  linked  image  of  the  user's  profile 
picture.  By  default,  it  is  a  50px  x  SOpx  image.  It  can  be  used  for  "iconifying" 
your  user  interactions. 

5.3  Profile  information 

Based  on  where  your  users  are  accessing  the  application  from,  you  can 
provide  different  content  to  them.  This  is  made  possible  by  using  the  various 
FBML  tags  for  customising  the  content  inside  the  user's  profile  box: 

•  <f  b :  wide>  -  This  tag  is  used  to  display  content  only  when  the  profile  box 
is  the  wide  column,  i.e.,  the  left  side. 

•  <fb:narrow>  -  This  tag  is  used  to  display  the  content  only  when  the 
profile  box  is  the  narrow  column,  i.e.,  right  side. 

•  <fb :prof  ile-action>  -  This  tag  builds  a  link  on  the  user's  profile 
under  their  photo.  You  can  use  this  in  conjunction  with  setFBML  to  send  any 
information  to  the  user's  profile. 

•  <fb:user-table>  -  This  tag  renders  a  table  of  the  users  you  have 
specified  by  the  <fb  :user-item>  tag. 
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•  <fb:user-item>  -  This  tag  is  used  to  define  a  user  for  use  inside  the 
<fb :  user-table>  tag. 

•  <fb :  subtitle>  -  This  tag  is  used  to  define  a  subtitle  for  the  profile  box. 

5.4  Embedded  media 

FBML  does  not  support  the  <embed>  tag  of  HTML  for  embedding  music, 
games  or  other  rich  content  in  your  application.  However,  there  are  several 
tags  which  offer  limited  functionality  in  this  are: 

•  <fb :  if  rame>  -  This  tag  is  used  to  insert  an  iframe  into  your  application 
so  that  you  can  pull  in  external  sources  to  your  application.  This  tag  can  only 
be  used  in  the  Canvas  page  and  not  in  the  profile  page. 

•  <f  b :  photo>  -  This  tag  renders  a  picture  that  is  in  the  Facebook  repository 
if  the  user  has  permissions  over  it. 

•  <fb  :mp3>  -  This  tag  adds  a  Flash-based  MP3  player  to  your  application 
that  controls  the  MP3  file  specified. 

•  <fb :  swf  >  This  tag  adds  a  Flash  player  to  render  a  Flash  object  on  the 
Facebook  pages.  However,  it  only  works  on  the  Canvas  page.  On  profile  page, 
the  SWF  file  is  rendered  as  an  image. 

•  <fb :  f  lv>  -  This  tag  adds  a  Flash-based  player  to  render  and  stream  FLV 
content,  .avi  and  other  extensions  are  still  not  supported. 

•  <fb :  silverlight>  -  This  tag  works  in  the  same  way  as  the  <fb  :  swf  > 
tag,  but  for  Silverlight-based  content. 

5.5  Profile  specific  content 

If  you  want  to  display  specific  content  to  your  users  depending  on  their 
profile  status  with  your  application,  FBML  provides  you  with  several  tags 
to  distinguish  between  the  application  owner,  users,  application  users  (those 
who  have  granted  full  access  to  your  application),  and  those  who  have  added 
the  application  to  their  accounts: 

•  <f  b :  visible- to-owner>  -  This  tag  is  used  to  display  content  if  the  user 
is  the  owner.  A  white  space  will  be  displayed  if  the  user  isn't  the  owner  in 
place  of  this  content. 

•  <fb :  visible-to-user>  -  This  tag  is  used  to  display  content  to  only  the 
specified  user. 

•  <f  b :  visible- to-app-users>  -  This  tag  is  used  to  display  content  only 
if  the  user  has  granted  full  permissions  to  your  application. 

•  <fb : visible-to-added-app-users>  -  This  tag  is  used  to  display 
content  only  if  the  user  has  added  the  application  to  their  account. 
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5.6  Forms 

FBML  has  several  tags  which  facilitate  working  with  form  information  and 
perform  some  common  tasks: 

•  <  f  b :  r  eque  s  t-  f  orm>  to  create  a  form  for  sending  requests.  You  can  let  your 
users  send  requests  to  add  the  application  (when  used  with  the  <fb:multi- 
f  r  iendseletor>  tag).  This  tag  is  invalid  when  working  with  iframes. 

•  <fb :  request-f  orm-submit>  to  create  a  submit  button  for  use  with  the 

<fb  :  request-f  orm>  tag. 

•  <fb  :multi-f  riend-input>  to  render  a  multifriend  input  field  like  the 
one  used  in  the  message  composer. 

•  <fb :  f  riend-selector>  to  render  an  autocomplete  input  box  of  the 
user's  friends. 

•  <f  b :  submit>  to  create  a  JavaScript  submit  button  for  your  forms.  If  you 
want  to  use  an  image  instead  of  a  submit  button,  you  can  use  this  like 

•  <fb : submitximg  src="path/to/image"  /></fb: submit> . 

5.7  Others 

FBML  has  a  set  of  tags  that  help  you  build  some  very  useful  portions  of 
your  application: 

•  <fb :  comments>  to  add  comments  to  an  application.  You  can  post  and 
redraw  pages  that  are  posted  to  for  a  given  UID. 

•  <f b :  google-analytics>  to  add  JavaScript  to  your  application  so  you 
can  use  Google  Analytics  to  track  your  application  usage. 

•  <fb:mobile>  to  displays  content  for  mobile  users  (http: //m. 
facebook.com).  Content  not  enclosed  within  this  tags  will  be  ignored  for 
mobile  users. 

•  <fb:random>  to  randomly  rotates  certain  parts  of  your  application 
content  (for  quotes,  pictures,  or  even  advertising).  This  tag  randomly  choose 
an  element  from  within  the  tag  (defined  by  the  <f  b :  random-option>  tag) 
and  also  allows  you  to  weight  these  options  to  appear  more  often  (or  less 
often)  than  other  options. 

•  <fb :  j  s-string>  define  a  string  to  reference  later  in  FBJS. 

•  <  f  b :  f  bml  >  define  the  version  of  FBML  you  wish  to  use. 

•  <fb :  fbmlversion>  to  display  the  version  of  FBML  that  is  currently 
being  used. 

•  <fb :  redirect>  to  redirect  the  browser  to  another  URL  in  your 
application. 

•  <fb :  ref  >    define  FBML  that  resides  at  a  URL  that  you  then  call  later 
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through  the  tag. 

•  <f  b :  share-button>  to  create  a  share  button  with  either  URL 
information  or  specific  metadata. 

•  <fb :  time>  to  render  the  time  in  the  user's  time  zone. 

•  <fb :  title>  to  set  the  page's  title  tag. 

5.8  Editor  Display 

FBML  has  a  set  of  tags  used  to  work  with  editing  data.  The  rendered  forms 
display  in  two  columns  with  the  label  on  the  left  and  an  input  field  on  the 
right.  The  form  the  <fb:editor>  tag  produces  uses  the  Post  method.  The 
different  tags  that  can  be  used  are: 

•  <fb:editor>  The  outermost  tag  used  to  create  an  editable  form. 

•  <f  b :  editor-button>  to  create  a  button  for  your  form. 

•  <f  b :  editor-buttonset>  to  create  a  container  for  one  or  more  buttons. 

•  <f  b :  editor-cancel>  to  create  a  cancel  button  for  the  form. 

•  <f b :  editor-custom>  to  insert  custom  FBML  code,  as  long  as  it's  valid 
FBML. 

•  <fb:editor-date>  to  create  two  select  boxes  in  the  form  for  the  month 
and  day. 

•  <f  b :  editor-divider>  to  add  a  horizontal  line  divider  to  your  form. 

•  <f  b :  editor-month>  to  create  a  select  box  populated  with  the  months  of 
the  year. 

•  <f  b :  editor-text>  to  create  an  input  box  for  your  form. 

•  <f  b :  editor-textarea>  to  create  a  textarea  box  for  your  form. 

•  <fb:editor-time>  to  create  select  boxes  for  hours,  minutes,  and  an 
a.m./p.m.  denotion  for  your  form. 

5.9  Page  navigation 

To  build  a  navigation  scheme  for  your  users,  the  main  FBML  tag  is  the 
<f  b :  dashboard>  tag  that  builds  the  familiar  dashboard  layout  in  Facebook. 
Once  you  do  that,  you  can  use  these  additional  tags  to  manage  the  lay  out 
within  the  dashboard,  including  buttons,  hyperlinks,  and  help: 

•  <  f  b :  a  c  t  i  on  >  Is  used  in  the  same  way  as  the  anchor  tag  in  the  dashboard. 

•  <fb:help>If  you  want  to  create  a  link  to  the  help  page  of  your  application. 
This  will  be  rendered  at  the  right  side  of  the  dashboard. 

•  <fb :  create-button>  To  create  any  button  in  the  dashboard. 

•  <fb:header>  Title  Header. 

•  <fb:  media-header >  Media  header,  generally  used  to  display  user 
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contributed  content  to  specific  users. 

•  <f  b :  tabs>  use  it  to  add  tabbed-navigation  style  links  to  your  application. 
Individual  tab  items  can  be  added  with  the  <fb :  tab-item>  tag. 

You  can  nest  the  <fb:action>,  <fb:help>,  and  <fb:  create-button> 
tags: 

<fb: dashboard> 

<fb: action  href=" . ">Add  </fb:action> 
<fb: action  href=" . ">Delete  </fb:action> 
<fb:help  href =" . ">Help  e</fb:help> 

<f b : create-button  href=".">Add  </fb : create-button> 
</fb:dashboard> 

But  the  <f  b :  tabs>  tag  only  allows  the  <f  b :  tab>  tag  to  be  nested: 
<fb: tabs> 

<fb:tab_item  href=" . "  title="Add"  /> 
<fb:tab_item  href=" . "  title="Delete"  /> 
<fb:tab_item  href=" . "  title="Help"  /> 
</fb:tabs> 

Typically  you  should  use  the  <fb:tabs>  tag  for  creating  an  overall 
navigation  schema,  and  the  <fb:dashboard>  tag  for  performing  functions 
within  your  application. 

5.10  Dialog  boxes 

These  tags  provide  the  modal  dialog  boxes  for  your  application,  which  is 
nothing  but  a  really  fancy  pop-up  box  used  to  interact  with  your  users.  It  is 
an  alternative  to  using  FBJS  to  create  this  type  of  interaction  between  your 
users  by  utilizing  the  Dialog  Box  Javascript. 

<f  b :  dialog>  Creates  the  container  for  the  dialog  box. 

<f  b :  dialog-title>  Set  the  title  for  your  dialog  box. 

<fb :  dialog-content>  Used  to  write  the  message  contained  in  the 
dialog  box. 

<f  b :  dialog-button>  Used  to  renders  button  for  your  dialog  box. 
The  FBML  snippet  for  constructing  a  dialog  box  goes  like: 
<fb:dialog  id="fb_test"> 

<fb: dialog-title>Sample  Dialog  Box</f b : dialog-title> 
<f b : dialog-content>Content</ f b : dialog-con tent> 
<fb : dialog-button     type="button"     value="Okay"  close_ 
dialog="l"  /> 
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</fb:dialog> 

<a   href=""    clicktoshowdialog="f b  est">show  fb:dialog</ 

a> 

Within  the  <fb:dialog-content>  tag,  you  can  add  other  information 
(and  other  FBML)  tags,  such  as  forms  to  perform  more  advanced  interactions 
with  your  users. 

To  generate  a  search  form  to  search  Faceboo,  use  the  following  code 
snippet: 

<fb:dialog  id="fb  search"  cancel  button="true"> 
<fb : dialog-title>Search  Facebook</ f b : dialog-title> 
<fb : dialog-content> 

<form  action  =  "http://www. facebook. com/ s  .  php " 

method="get"> 

<input  type="text"  name="q"  /> 

<input  type=" submit"  value="Search"  /> 

</ f orm> 

</f b : dialog-content> 
</fb:dialog> 

<a   href=""    clicktoshowdialog="fb_search">Show  Search</ 

a> 

If  you  are  not  a  JavaScript  expert,  the  <fb:dialog>  tags  will  provide  a  very 
convenient  method  to  do  most  of  the  same  things  you  can  do  with  FBJS 
without  writing  any  FBJS. 

5.11  Wall 

FBML  tags  which  add  the  functionality  to  your  application  which  concerns 
with  users  interacting  with  their  wall  are 

•  <f b :  wall>  Your  application  will  render  a  wall-like  section  that  has  the 
<fb :  wallpost>  elements  from  your  application  users. 

•  <fb:wallpost>  Used  to  handle  the  message  for  the  wall  post  that  can 
contain  an  <f  b :  wallpostaction>  element. 

•  <fb :  wallpost-action>  Used  to  add  a  link  at  the  bottom  of  the 
wall  post. 

You  just  need  to  make  a  new  table  with  three  tuples  (columns)  to  hold  the 
UID  (bigint),  the  actual  post  (text),  and  a  time  stamp  (for  indexing)  to  handle 
wall  posts.  Additionally,  you  can  add  a  primary  key  field,  though  the  time 
stamp  should  suffice  for  this.  Now,  loop  over  these  results  to  provide  them  in 
the  <fb:  wallpost>  tags,  and  wrap  it  in  <fb :  wall>.  El 
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JavaScript  is  essential  for  developing  enriched  user  interfaces.  As  a  result, 
Facebook  came  out  with  its  own  version  of  JavaScript  called  Facebook 
JavaScript. 

6.1  FJS  essentials 

Facebook  takes  the  FBJS,  parses  the  code,  and  prepends  functions  and 
variable  names  with  your  application  identifier. 
For  example: 

function  say  hello (name) { 
var  my  string  =   'Hello  World'; 
return  my  string  +    '    '    +  name; 
} 

is  converted  into: 

function  <app  id>  say  hello (<app  id>  name) { 
var  <app  id>  my  string  =   'Hello  World'; 
return  <app  id>  my  string  +  <app  id>  name; 
} 

You  also  need  to  keep  a  few  things  in  mind  when  you  are  using  FBJS  in 
your  applications.  Your  scripts  will  perform  differently  in  different  areas  of 
the  application. 

For  example,  let's  see  how  the  following  example  from  the  Facebook  wiki 
behaves: 

<a     href="#"      id="hello"      onclick="hello_world (this ) ; 
return  false; ">Hello  World!</a> 
<script> 
<!  — 

function  random  int(lo,    hi)  { 

return  Math . floor ( (Math . random ( )    *    (hi  -  lo) )    +  lo)  ; 
} 

function  hello  world (obj)  { 

var  r  =  random  int(0,  255); 

var  b  =  random  int(0,  255); 

var  g  =  random  int(0,  255); 

var  color  =  r+ ' ,    ' +g+ ' ,  '+b; 

obj . setStyle ( ' color  ' ,    ' rgb ( ' +color+ ' )  '  )  ; 


thinkd\9\t 


49 


FAST  TRACK-  APRIL  2010 


□  FOL  and  FJS 


Creating  Facebook  Apps 


} 

hello_world (document . getElementByld ( 'hello' ) ) ; 

II— > 

</ script> 

This  program  randomly  sets  the  colour  of  the  anchor  text  "Hello  World". 
However,  it  will  behave  differently  depending  on  where  your  application 
is  located.  In  the  profile  box,  inline  scripts  like  these  are  deferred  until  the 
first  "active"  event  is  triggered  (for  example,  anything  that  requires  a  mouse 
click).  But,  it  works  perfectly  fine  in  on  the  Canvas  page. 

6.1.1  Creating  a  Drop-Down  Menu  in  FBJS 

You  can  create  Drop  down  menus  in  your  Facebook  application  with  the  help 
of  FBML  and  FBJS.  Here's  how: 

<div  style="padding: 20px"> 

<div  class="nav"  > 

<ul> 

<11  style="width: 70px;  "  id="home"  > 

<div><a  onclick= ' displayMenu ( "homechild" )  '  href = ' # ' >Home 
</a></div> 
</li> 

<li  style="width:  HOpx;  "  > 

<div><a  onclick=' displayMenu ( "abchild" ) ' 

href=' # ' >Addressbook</a></div> 

<ul  id="abchild"  style="background-color :blue"> 

<li><a  href ="#">S tor ies</ax/li> 

<lixa  href="#">Articles</a></li> 

<lixa  href="#">Game  REviews</a></li> 

</ul> 

</li> 

<li  style="width:  HOpx;  "  > 

<div><a  onclick= ' displayMenu ("helpchild")  '  href = ' # ' >Help 
</a></div> 

<ul  id="helpchild"  style="background-color : blue"  > 

<lixa  href="#">Topics</a></li> 

<lixa  href="#">Contact  us</ax/li> 

</ul> 

</li> 

</ul> 
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</div> 

<div  style="margin-top : 140px"  ></div> 
</div> 

Next,  add  this  stylesheet  to  make  them  display  properly: 

<style> 
. nav  ul 
{ 

width:  100%; 
list-style:  none; 
line-height:  1; 
height : 60px; 
font-weight:  bold; 
padding:  Opx; 
border-width:   lpx  lpx; 
margin :    0   0   0   0 ; 
} 

.nav  li  { 
float:  left; 
padding:  Opx; 
padding-top: 25px; 
margin-bottom: lOpx; 
} 

.nav  li  ul 
{ 

display : none; 

padding: 5px; 

padding-left : Opx; 

background-color: transparent; 

margin-top : lOpx; 

position:  absolute; 

height:  auto; 

width:  lOOpx; 

font-weight:  normal; 

border-width:  0.25em; 

margin:  Opx; 

} 

.nav  li  ul  li{ 
float : none; 
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padding-top:  5px; 
padding-bottom: 5px; 
padding-left : 15px; 
color : white; 
} 

. nav  a: hover { 

text-decoration : underline; 
} 

.nav  li  ul  li  a 
{ 

color : white; 
text-decoration : none; 
} 

</style> 

And  finally,  write  the  following  FBJS  code: 

<script> 

function  displayMenu (ch) 
{ 

document  .getElementByld  ("abchild"  )  . 
setStyle ( ' display ' , ' none ' ) ; 

document  .  getElementByld  (  "helpchild"  )  . 
setStyle ( ' display ' , ' none ' ) ; 

try  { 

document.   getElementByld   (ch)  . 
setStyle ( 'display' , 'block' ) ; 
} 

catch  (e)  { } 
} 

</ script> 
6.1.2  Dialog 

If  you  are  not  content  with  the  Dialog  box  creation  abilities  of  FBML,  you 
can  do  so  in  FBJS  also  very  easily.  Here's  the  code  required  to  create  a  Dialog 
object:  Var  dialog  =  new  Dialog  (); 

To  display  information  within  your  Dialog  box,  Use  the  showMessage() 
method  of  a  Dialog  along  with  its  three  parameters: 

<script> 

new     Dialog (). showMessage ( "Hello     World", "Are      you  a 
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G33 | <", "Boring! ") ; 
</ script> 

To  accept  User  input  using  FBJS,  you  need  to  use  the  showChoice() 
method  of  the  Dialog  object  along  with  its  four  parameters: 

dialog . showChoice (' Wheee ' ,    'mmmmm'    ,':-/',' Loser ') ; 

To  manage  the  user  input,  after  they  click  Okay  or  Cancel: 

dialog . onconfirm  =  function  ( )  {new  DialogO  . 
showMessage ("Info", "OK") } ; 

dialog . oncancel  =  function ( ) {new  DialogO  . 
showMessage ("Info", "Cancel") } ; 

So,  the  final  script  will  be  like  this: 

<script> 

var  dialog  =  new  DialogO; 

dialog . showChoice (' Wheee ' ,    'mmmmm'    ,':-/',' Loser ') ; 

dialog . onconfirm  =  function  ( )  {new  DialogO  . 
showMessage ("Info", "OK") }  ; 

dialog . oncancel  =  function ( ) {new  DialogO  ■ 
showMessage ("Info", "Cancel") } ; 

</ script> 

In  FBJS,  you  can  display  two  types  of  dialog  box:  popup,  and  contextual. 
For  a  contextual  dialog,  use  the  following  code: 
<div  style="padding: 20px"> 

<a  id="link"  style= ' cursor :pointer '  onclick="showDialog 
(this) ; ">Click  to  see  a  contextual  dialog  box</a> 
</div> 
<script> 

function  showDialog (linker) { 

//context  =  document . getElementByld (" link" )  ; 
new  Dialog (Dialog. DIALOG_CONTEXTUAL)  . setContext ( linker )  . 
showMessage ( "HelloWorld" ) ; 
} 

</ script> 

You  need  to  call  setContext()  before  calling  showMessage()  or  showChoice(). 
If  you  call  it  later,  the  dialog  will  not  be  shown  in  the  right  place,  instead  it 
will  go  to  the  top  left  corner  of  the  page. 

6.1.3  Advanced  input 

Apart  from  a  Boolean  input  like  Okay  or  Cancel,  you  can  take  multiple  from 
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your  users  and  even  pass  any  valid  pre-rendered  FBML  block  to  dialogs.  The 
following  example  shows  how  to  take  written  inputs  from  your  users. 

<div  style="padding: 20px"> 

<a  id="link"  href="#"  onclick=" showDialog (this) ; ">Click 
to  see  a  contextual  dialog  box</ a> 
</div> 

<fb : j s-string  var= ' inputs ' > 
Wassaa??  <br/> 

<input  type="text"  id="userinput"  /> 

</f b : j  s-string> 

<script> 

function  showDialog (linker) { 

//context  =  document . getElementByld (" link" )  ; 

New  Dialog (Dialog . DIALOG_CONTEXTUAL)  . 

setContext (linker ) . showMessage ( "Greeting" , inputs , "Okay" ) . 
onconfirm=f unction ( ) { 

data  =  "So,  you're  upto  "  +  document. 
getElementByld ( "userinput" ) . getValue()  +"Pretty  cool 
man ! " ; 

new  Dialog ()  . showMessage ( "Info" , data,  "OK" )  ; 
return  false; 

}; 

} 

</ script> 
6.1.4  Events 

Managing  events  in  FBJS  is  pretty  simple  if  you  are  familiar  with  event 
management  in  JavaScript  because  its  almost  is  the  same.  You  can  use  the 
addEventListener  ()  function  to  attach  listeners  to  an  event.  It  takes  two 
arguments;  the  name  of  the  event  to  listen,  and  the  callback. 

Let's  try  this  with  an  example: 

<div  style="padding: 20px"> 

<div  id="somediv"> 

Your  Content 

</div> 

<input  type="button"  id="somebutton"  value="Click  Me"  /> 

</div> 

<script> 
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button  =  document . getElementByld ( "somebutton" ) ; 
button . addEventListener ( "click" , hide ) ; 
function  hide (event) 
{ 

document  .  getElementByld  (  "  somediv"  )  . 
setStyle ( "display" , "none" ) ; 
} 

</ script> 

To  find  out  who  fired  the  event,  use  the  event.target.getld()  method  of  an 
event  object. 

function  hide (event) 
{ 

document  .  getElementByld  (  "  somediv"  )  . 
setStyle ( "display" , "none" ) ; 

usedby  =  event . target . getld ()  ; 

new  Dialog () . showMessage ( "Info", "This  event  was  used  by 
"+usedby+" ", "Okay") 
} 

When  you  attach  an  event  to  a  Data  Object  Model  node,  the  event  gets 
automatically  added  to  all  the  child  nodes  in  that  node.  So  just  which  object 
is  invoking  the  event  listener,  and  then  take  action  using  getld(). 

There  are  other  useful  methods  available  to  this  event  object,  which  are 
essential  in  developing  sophisticated  event-based  applications: 

•  stopPropagation  ( )  —Stop  the  propagation  of  the  event  further  to  any 
DOM  sub-  node. 

•  cancelDef  ault  ( )  —Cancel  the  default  behaviour  of  an  event. 

•  listEventListeners  (eventName)  —Return  an  array  of  handles  of  the 
events  which  have  been  added  to  this  event.  It  also  includes  the  events  that 
were  added  in  FBML  using  the  <event>  attribute. 

•  purgeEventListeners  (eventName) —Remove  all  event  listeners  for 
this  event. 

Example: 

<div  style="padding: 20px"> 

<textarea  id=" sometextarea"> 

</ textarea> 

</div> 

<script> 

ta  =  document . getElementByld ( "sometextarea" ) ; 
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ta . addEventListener ( " keydown" , keydown) ; 

function  keydown (ev) 

{ 

keycode  =  ev.keyCode; 

if  (keycode==83) 

ev . preventDef ault ( ) ; 

//new  Dialog (). showMessage ( "Info"  ,  "you  just  pressed 

"+keycode+" " , "OK" ) 

} 

</ script> 

6.2  FQL  essentials 

FQL  uses  the  same  syntax  as  typical  ANSI-SQL,  so  if  you've  worked  with 
SQL  before  (and  I  assume  you  have),  FQL  isn't  a  big  deal.  There  are  only  nine 
tables  to  deal  with  and  no  joins.  FQL  does  not  implement  the  LIMIT,  GROUP 
BY,  or  ORDER  BY  clauses  that  are  common  to  ANSI  SQL-compliant 
implementations.  Let's  take  a  look  at  the  tables  and  fields  that  are  part  of  the 
Facebook  Query  Language. 

6.2.1  Tables 

Here's  a  list  of  different  tables  or  views  of  specific  data  to  make  sure  you 
know  what's  available  to  you. 

•  users (uid,  first  name,  last  name,  pic  small,  pic  big, 
pic  square,  affiliations,  profile  update  time,  timezone, 
birthday,  sex,  hometown  location,  meeting  sex,  meeting_ 
for,  relationship  status,  significant  other  id,  political, 
current_location,  activities,  interests,  is_app_user, 
music,  tv,  movies,  books,  quotes,  about_me,  hs_info, 
education  history,  work  history,  notes  count,  wall  count, 
status,  has_added_app) 

•  friend (uidl,  uid2) 

•  group (gid,  name,  pic_small,  pic_big,  pic,  description, 
group_type,  group_subtype,  recent_news,  creator,  update_ 
time,   office,   website,  venue) 

•  group  member (uid,  gid) 

•  event (eid,  name,  tagline,  pic_small,  pic_big,  pic,  host, 
event_type,  event_subtype ,  start_time,  end_time,  creator, 
update_time,    location,  venue) 
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•  event_member (uid,   eid,  rsvp_status) 

•  photo (pid,  aid,  owner,  src_small,  src_big,  src,  caption, 
created) 

•  album (aid,  cover_pid,  owner,  name,  created,  description, 
location,  size) 

•  photo_tag (pid,    subject,   xcoord,  ycoord) 
6.1.3  Functions  and  operators 

FQL  has  several  simple  operators  and  functions  to  help  you  work  with 
user  data.  There  are  Boolean  operators  (AND,  OR,  and  NOT),  comparison 
operators  (=,  >,  >=,  <,  <=,  <>),  and  arithmetic  operators  (+,  -,  *,  and  /).  The 
functions  included  in  FQL  also  allow  you  to  perform  some  basic  string 
manipulations,  although  not  very  exhaustively. 

•  now ( )    -  This  returns     the  current  time. 

•  strlen (string)  -  return  the  length  of  the  string  passed 
to  the  function. 

•  concat  (stringl,  string2,...,  stringn)  -  concatenate  n 
strings  together. 

•  substr (string,  start,  length)  -  return  a  substring  from 
a  given  string. 

•  strpos (haystack,  needle)  -  return  the  position  of  the 
character  needle  in  the  string  haystack. 

•  lower ( string)    -  cast  the  given  string  to  lowercase, 
upper (string)    -  cast  the  given  string  to  uppercase. 

Example: 
<?php 

$facebook_conf ig [' debug ' ]   =  false; 

$ facebook  config['api  key']    =   '<your  api  key>'; 

$facebook  config [' secret  key']   =   '<your  secret  key> ' ; 

require  once('<path  to  client  library>/f acebook . php ' ) ; 

$facebook  =  new  Facebook ($facebook_conf ig [' api_key '] , 

$f acebook_conf ig [ ' secret ' ] ) ; 

$user  =  $f acebook->require  login (); 

$fql  =  "SELECT  concat ( first_name,    '    ',  last_name) 

FROM  user 

WHERE  uid  =  '$user'"; 

$fql_result  =  $f acebook->api_client->f ql_query ( $f ql )  ; 
echo   "<pre>FQL  Result:"    .   print_r ( $f ql_result,  true) 
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"</pre>" ; 

?> 

This  simply  selects  the  first  and  last  names  of  the  user  who  is  currently 
making  the  request.  The  result  will  be  an  array  in  the  following  format: 

FQL  Result: Array 

[0]    =>  Array 

[anon]   =>  <your  first  name>  <your  last  name> 

We've  used  the  concat()  function  to  group  several  tuples  together  to 
conserve  bandwidth.  You  can  also  use  this  to  put  a  specific  string  into  your 
page  that  combines  several  fields  in  a  specific  way.  Letting  the  Facebook 
servers  do  some  of  this  processing  before  it  gets  back  to  your  server  will  cut 
down  on  your  bandwidth  in  order  to  speed  up  your  application  and  decrease 
your  server  load.  You  can  also  perform  various  subqueries.  For  example, 
FQL  equivalent  for  the  facebook.events.get  REST  API  call  goes  like: 

SELECT  eid,  name,  tagline,  nid,  pic,  pic  big,  pic  small, 
host,  description,  event_type,  event_subtype,  start_time, 
end_time,   creator,   update_time,    location,  venue 

FROM  event 

WHERE  eid  IN    (SELECT  eid  FROM  eventjnember 

WHERE    uid=uid   AND    rsvp_status=rsvp_status )    AND   eid  IN 

(eids)    AND  end  time   >=   start  time  AND   start  time   <  end_ 

time 

Nested  queries  like  these  are  very  useful  for  testing  set  membership, 
set  comparisons,  and  set  cardinality.  You  will  however  need  to  take  some 
additional  processing  to  make  sure  your  information  is  displayed  in  a 
specific  order  in  your  client  language  like  PHP.  If  you  want  to  sort  the  array 
and  then  slice  it: 

<?php 

$fql  =  "SELECT  eid,    name,  location 

FROM  event 

WHERE  eid  IN  ( 

SELECT  eid 

FROM  event  member 

WHERE  uid  =  '$user' 
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)  "; 

$fql  result  =  $f acebook->api  client->fql  query ($fql) ; 
asort ($fql_result) ; 
array_slice ($fql_result,    0,    4) ; 
?> 

An  FQL  query  is  passed  to  find  events  for  the  current  user,  sort  the 
resulting  PHP  array,  and  returns  the  array  with  the  five  elements  (positions 
0-4)  of  the  query  result. 

FQL  gives  developers  granular  control  of  the  information  about  your 
users  from  the  Facebook  servers.  As  the  complexity  of  your  FQL  increases 
with  subqueries,  you  might  run  into  problems.  For  this,  you  can  use  the 
Facebook  API  Test  Console  at  http://developer.facebook.com/tools.php  to  debug  your 
code.  This  tool  provides  invaluable  help  in  discerning  where  your  bugs 
exist  when  you  are  working  with  more  complicated  interactions  with  FBML 
and  FQL.  H 
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□  Updating  profile  pages 


The  profile  page  of  Facebook  provides  a  snapshot  of  who  a  user  is  and  what 
he/she  finds  important.  A  Facebook  application  can  add  profile  boxes, 
application  tabs  and  info  sections  to  manipulate  this  information. 

7.1  Profile  boxes 

The  Profile  boxes  are  FBML  based  and  do  not  allow  profiles  to  use  IFrames 
or  Flash.  The  content  is  set  by  the  application  using  the  profile.setFBMLO 
API  call.  There  are  three  types  of  Profile  Boxes  in  Facebook,  namely  Main, 
Wide  and  Narrow.  The  Main  box  appears  on  the  left  side  of  the  Wall  and  the 
Info  tab  of  a  profile,  and  measures  184x250  pixels.  A  maximum  of  four  of 
these  appear  at  a  time  on  the  Profile  page,  and  the  rest  are  moved  to  the  Boxes 
tab.  The  Narrow  and  Wide  boxes  appear  on  the  Boxes  tab  by  default.  Wide 
appears  on  the  left  side  and  is  380  px  wide,  whereas  the  Narrow  appears  on 
the  right  and  is  184px  wide.  Both  of  these  don't  have  any  height  limitations. 
These  profile  boxes  can  be  moved  by  the  user  by  dragging  and  dropping, 
but  the  content  inside  a  <f b :  narrow>  tagged  box  only  shows  up  when  the 
profile  box  is  on  the  right  side,  while  content  in  a  <f  b :  wide>  tagged  box  only 
shows  up  on  the  left  side.  A  good  profile  box  will  support  both  the  locations 
by  displaying  the  content  formatted  appropriately  based  on  size  limitations. 

The  PHP  client  library  has  different  parameters  for  the  prof  ile_ 
setFBML  ( )  call: 


Parameter 

Details 

markup 

It  has  been  deprecated.  Just  pass  it  as  NULL. 

Uid 

This  denotes  the  user  ID  for  the  user  or  Public  Profile  to  update,  which  is 
set  to  the  current  user  by  default. 

profile 

It  is  a  string  parameter  which  contains  the  FBML  for  the  profile  box  on 
the  Boxes  tab. 

profile_action 

It  has  been  deprecated.  Just  pass  it  as  NULL. 

mobile_profile 

It  is  a  string  parameter  which  contains  the  FBML  that  appears  on 
http://rn.facebook.com. 

profile_main 

It  is  a  string  parameter  which  contains  the  FBML  that  appears  on  the 
Main  profile  box. 

Example: 

$ markup  =  NULL; 

$mainFBML  =  "Appears  on  the  Wall"; 
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$profileFBML  =  " 

<fb : narrow>Appears  on  right  side</f b : narrow> 
<fb:wide>Appears  on  left  side</f b : wide>" ; 
$mobileFBML  =  " 

<fb :mobile>Appears  on  m.  facebook . com</fb :mobile>" ; 
$prof ileAction  =  NULL; 

$facebook  =  new  Facebook (FB_API_KEY,   FB_APP_SECRET) ; 
$ f a ceboo k- >ap i   c 1 i en t- >p r o f i 1 e   setFBML ( $mar kup , 
$appUserID,    $prof ileFBML, 

$prof ileAction,    $mobileFBML,    $mainFBML) ; 

7.2  Creating  the  Profile  Box 

We  will  update  our  sample  application  to  use  all  the  profile  boxes  in  this 
section.  These  profile  boxes  lets  you  send  feedback.  There  is  a  Send  button 
that  takes  the  user  back  to  the  application  Canvas  page. 

Add  a  call  to  the  updateProf  ileBox  ( )  function  in  index.php  and  index 
iframe.php  by  inserting  the  command  updateProf  ileBox  (  $f acebook- 
>user  )  ;  just  before  renderPage  ( ) : 

Create  a  File  called  profile.inc  inside  the  inc  directory  on  your  server.  This 
file  will  contain  all  the  code  related  to  creating  profile  content  and  updating  it 
on  Facebook.  You  also  need  to  add  require  once  '  inc/prof  ile .  inc '  ; 
to  the  top  of  your  index.php  and  index  iframe.php  files.  The  following  source 
code  goes  into  the  profile.inc  file: 

<?php 

function  updateProf ileBox ($appUserID) { 
$facebook  =  new  Facebook (FB_API_KEY,   FB_APP_SECRET) ; 
$generatedProf ileFBML    =    generateProf ileBoxFBML ( $appUse 
rID)  ; 

$prof ileFBML  =  $generatedProf ileFBML [ 'profile  '  ]  ; 
$mainFBML  =  $generatedProf ileFBML [ 'main '] ; 
try  { 

$f acebook->api_client->prof ile_setFBML (NULL,  $appUserID, 
$prof ileFBML,    NULL,   NULL,    $mainFBML) ; 
}        catch   (Exception  $ex)  { 

wr ( "<Exception :  uid:  $appUserID  -  "  .  $ex->getMessage ( ) 
.  ">"  )  ; 

return  false; 
} 
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return  true; 
} 

function  generateProf ileBoxFBML ( $appUserID)  { 
global  $g_categories ; 

$styles      =     htmlentities (f ile_get_contents (LOCAL_APP_ 
DIR.  '  /  ess/pro file. ess'  )  , 
true) ; 

$headerBlock  =  " 

<style> 

$styles 

</style> 

<fb:subtitle> 

<fb taction  href = ' " . FB_APP_URL . " ' >Send  Feedback</ 
f b : action> 

</fb:subtitle>"; 
$categories  =  ""; 

f oreach (   $g_categories  as  $name  =>  $info  ){ 

$categories  .=" 

<div  class= ' category ' > 

<img  class= ' categorylmg '   title= '{ $info [' title ']} ' 

src=' " .LOCAL_APP_URL. "/img/" . $inf o [ ' smallimg' ] . " ' /><br> 

<div  class='categoryTitle'>{$info[ 'title' ] }</div> 

<input  type=' radio'   name= ' category '  value= ' $name '  /> 

</div>"; 

} 

$formBlock  =  " 

<div  class= ' sendFeedback '  > 

<span  class= ' sendTitle ' >Send  Feedback</span> 
<form  method='POST'   id= ' FeedbackForm'   action= ' " . FB_APP_ 
URL."/'  > 

<div  class= ' categories ' > 
$categories 

<div  style= ' clear : both; ' ></div> 
</div> 

<input  type= ' hidden '   name= ' target '   value= ' $appUserID ' /> 
<input  class= ' textlnput '   name= ' Feedback ' /><br/> 
<input  class= ' inputbutton  '  type= ' submit ' 
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name= ' submitFeedback ' 
value= ' Send ' > 
</ f orm> 
</div>"; 

$wideContent  =  " 
<fb:wide> 

<div  class= ' wide '  > 

<div  class= 'prof ileContent '  > 

<img  class= ' banner '  src='". LOCAL  APP  URL . " /img/banner  w. 
png ' /> 

$f ormBlock 

</div> 

</div> 

</fb:wide>"; 

$narrowContent  =  " 

<fb : narrow> 

<div  class= ' narrow ' > 

<div  class= 'prof ileContent ' > 

<img  class= ' banner '  src= ' " . LOCAL_APP_URL . " /img/banner_n . 
png ' /> 

$f ormBlock 

</div> 

</div> 

</ f b : narrow>" ; 

$mainContent  =  " 

<div  class= 'main ' > 

<div  class= 'prof ileContent ' > 

<img  class= ' banner '  src= ' " . LOCAL_APP_URL . " /img/banner_n . 
png ' /> 

$f ormBlock 

</div> 

</div>"; 

$prof ileText [ 'prof ile '  ]  =  $headerBlock  .  $wideContent  . 
$narrowContent; 

$prof ileText [ 'main ' ]   =  $headerBlock  .  $mainContent; 

return  $prof ileText; 

} 

?> 
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7.3  Styling  the  Profile  Boxes 

To  add  style  for  the  profile  boxes  you  create  using  the  above  methods, 
create  a  new  file  called  profile.css  in  the  CSS  directory  and  add  the  following 
source  code. 

. prof ileContent   {  margin-top : -12px;   text-align : center ; } 
. sendFeedback  {   text-align: center; } 
. sendTitle   {font-weight:  bold;} 
#FeedbackTable   .textlnput   {width:   200px; } 
.categories   {  padding-bottom:   5px;  } 
. categoryTitle   {  height :30px;   font-weight : bold;  } 
.category    {    float: left;    text-align : center ;  margin:3px; 
width: 43px; 

height :65px;   padding: 5px;  } 

. categorylmg  {  width:24px;   height : 24px; } 

.wide   .banner   {  width:380px;   height:45px;  } 

.wide   .category   {  width: 108px;  } 

.wide   .categoryTitle   {  height : 20px; } 

.narrow   .banner   {  width:193px;   height:23px;  } 

.main   .banner   {  width:193px;   height : 23px; } 

7.4  Adding  the  Profile  Boxes 

Profile  boxes  do  not  get  automatically  added  to  a  user  profile.  The  user  must 
manually  choose  to  add  one  to  his  profile  by  clicking  on  a  button. 

7.4.1  Displaying  Add  to  Profile  Buttons  in  FBML  Canvas  Pages 

Displaying  the  Add  to  Profile  button  is  very  simple  for  an  FBML  canvas 
page.  Just  add  the  following  code  to  the  renderPage()  function  in  index.php, 
after  the  banner  in  the  header  block.  The  <fb :  if-section-not-added 
section= 'prof  ile  '  >  tag  makes  sure  Facebook  only  renders  the  inside 
FBML  if  the  user  hasn't  added  the  profile  box  yet.  The  <f  b :  addsection- 
button  section='prof  ile  '  />  tag  actually  renders  the  button.  All  of 
this  is  enclosed  in  a  <div>  so  that  we  can  position  it  where  we  want  on  the 
page  using  CSS. 
index . php 

<div  class= 'banner ' 

style='background:  url (" . LOCAL_APP_URL . " /img/banner . 
png)   no-repeat; '  > 

<div  id= ' buttons '   class= ' clearf ix '  > 
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<div  id= ' addbutton ' > 

<fb : if -section-not-added  section= ' prof ile ' > 

<fb : add-section-button  section= 'prof ile '  /> 

</ f b : if-section-not-added> 

</div> 

</div> 

</div> 

7.4.2  Displaying  Add  to  Profile  Buttons  in  IFrame  Canvas  Pages 

Adding  the  Add  to  Profile  button  in  an  IFrame  Canvas  Page  is  slightly  more 
tricky  because  there  is  no  way  to  create  this  button  without  using  FBML 
and  IFrames  don't  support  FBML.  We  need  to  use  XFBML  for  this,  which 
requires  the  Facebook  JavaScript  Client  Library  and  all  the  supporting  code. 

The  first  step  in  this  is  to  update  the  Developer  Settings  for  this  application. 
Browse  to  www.facebook.com/developers/apps.php  and  click  the  Edit 
Settings  link  for  Feedbacks.  Click  on  the  Connect  tab  and  enter  in  your 
Canvas  Callback  URL  into  the  Connect  URL  field  and  click  on  Save.  Next, 
create  a  file  named  xdreceiver.html  in  your  application  root  directory,  and 
add  the  following  source  code  into  it. 

xdreceiver . html 

<!DOCTYPE  html  PUBLIC  "-//W3C//DTD  XHTML  1.0  Strict//EN" 
"http : //www. w3 . org/TR/xhtmll/DTD/xhtmll-strict.dtd"> 
<html  xmlns="http: //www. w3.org/1999/xhtml"  > 
<head> 

<title>Cross-Domain  Receiver  Page</title> 

</head> 

<body> 

<script  src="http : / / static . ak. facebook. com/ j  s/ api_lib/ 
vO . 4/XdCommReceiver . j  s?2 " 

type="text/ j  avascripf'x/ script> 

</body> 

</html> 

The  Facebook  JavaScript  Client  Library  will  now  be  able  communicate 
with  your  application.  Next  create  a  placeholder  <div>  that  the  Library  can 
use.  The  renderPage()  function  in  index  iframe.php  should  now  look  like: 

<div  class= 'banner ' 

style='background:  url (" . LOCAL_APP_URL . " /img/banner . 
png)   no-repeat; '  > 
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<div  id= ' buttons '   class= ' clearf ix '  > 

<div  id='addbutton'x/div> 

</div> 

</div> 

Next  add  a  script  block  that  loads  and  initializes  the  Facebook  JavaScript 
Client  Library  and  tells  it  to  replace  the  placeholder  <div>  with  the  Add  to 
Profile  button.  Use  the  following  code  at  the  end  of  renderPage()  in  index 
iframe.php  ,  just  before  the  </body>  tag  to  accomplish  this. 

index  iframe.php 
$pageOutput  .=  " 
<script 

src='http://static.ak. facebook. com/js/api_lib/vO. 4/ 

FeatureLoader . j  s . php ' 

type= ' text/ j  avascr ipt ' ></ script> 

<script  type= ' text/ j avascript ' > 

FB_RequireFeatures ( [ 'XFBML' ]  ,    function ()  { 

FB  .  Facebook . init ( ' " . FB_API_KEY . " ' ,       ' xdreceiver . html ' , 

null) ; 

FB . Connect . showAddSectionButton ( 'profile ' , 
document . getElementByld ( ' addbutton ' ) ) ; 
FB . Connect . showAddSectionButton ( ' info ' , 
document . getElementByld ( ' inf obutton ' ) ) ; 
})  ; 

</ script> 

</body> 

</html> 

As  with  all  the  XFBML,  this  code  runs  on  the  client,  so  there  might  be  a 
slight  delay  as  the  library  needs  to  render  the  new  button  HTML.  To  test  the 
profile  boxes,  go  to  your  application  and  click  on  the  Add  to  Profile  button 
on  either  the  FBML  or  IFrame  tab.  Click  on  Add,  and  go  to  your  profile.  Click 
on  Keep  to  accept  the  new  profile  box.  You  can  try  moving  it  from  the  Wall 
to  the  Boxes  tab  and  from  the  Narrow  to  the  Wide  side  to  see  how  the  layout 
changes  with  each  location. 

7.5  Application  tabs 

If  you  want  your  applications  to  display  profile  content  in  a  much  larger 
space,  you  have  to  use  Application  tabs.  They  behave  like  profile  boxes,  but 
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are  760px  wide.  Application  tabs  are  different  in  the  sense  that  they  are 
populated  via  a  callback  instead  of  presetting  the  content  once  via  profile . 

setFBML ( )  . 

If  an  application  supports  an  application  tab,  the  user  can  click  on  the  +  at 
the  right  side  of  his  profile  tab  list  and  select  it  from  a  list  to  add  the  tab.  You 
need  to  update  the  Developer  Settings  to  allow  users  to  add  an  application 
tab  by  going  to  the  Profiles  tab  and  filling  in  Feedbacks  for  the  Tab  Name 
and  apptab.php  for  the  Tab  URL.  Next,  you  need  to  create  a  new  file 
named  apptab.php  in  the  application  root  directory  and  add  the  following 
source  code: 

<?php 

require  once  dirname (     FILE     ) . ' /inc/globals . inc ' ; 
require  once  dirname (     FILE     ) . ' /inc/db . inc ' ; 
require  once  dirname (     FILE     ) . ' /inc/utils . inc ' ; 
require  once  dirname (     FILE     ) . ' /inc/prof ile . inc ' ; 

dumpRequestVars (true,   basename (  FILE  ) ) ; 

$facebook  =  new  Facebook (FB_API_KEY,   FB_APP_SECRET) ; 
$generatedProf  ileFBML  =  generateProf  ileBoxFBML  ( $f acebook- 
>profile  user) ; 

$appTabFBML  =  $generatedProf ileFBML [ ' tab ' ] ; 

echo  $appTabFBML; 

?> 

This  file  acts  as  the  handler  for  the  application  tab  callback  and  reuses 
functionality  from  profile.inc  to  help  generate  the  FBML.  The  code  calls  the 
generateProfileBoxFBMLO  function  and  gets  the  FBML  for  the  tab  and  then 
echoes  it  out.  Update  profile.inc  with  the  following  source  code  to  add  the  tab 
specific  content. 

$appTabHeaderBlock  =  " 

<style> 

$styles 

</style> 

<div  class= ' subtitle ' > 

<a  href=' " . FB_APP_URL. " ' > 

Send  a  Feedback 

</a> 

</div>"; 

$tabContent  =  " 

<div  class='tab'> 
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<div  class= 'prof ileContent ' > 

<img  class='banner '  src= ' " . LOCAL_APP_URL . " /img/banner . 
png' /> 

$f ormBlock 

</div> 

</div>"; 

$prof ileText [ 'tab' ]   =  $appTabHeaderBlock  .  $tabContent; 

Add  the  $appTabHeaderBlock  section  just  after  the  $headerBlock  in 
your  file  and  the  $tabContent  section  after  $mainContent. 

Note  that  application  tabs  do  not  support  the  <fb:  subtitle>  tag  we 
used  for  the  profile  boxes,  so  we  will  have  to  manually  create  the  link.  Just 
like  the  other  profile  boxes,  enclose  the  FBML  in  a  <div>  tag  with  the  class 
tab  so  that  you  can  apply  custom  styles. 

profile. ess  file  needs  to  be  updated  with: 

.tab   .banner   {   width : 7 60px;   height : 90px;  } 

.tab   .sendTitle   { font-size : 20px;  } 

.tab   .category  {   width: 108px;  } 

.tab   . categoryTitle   {   height : 15px;  } 

.tab   .textlnput   {  width:    400px;  } 

.tab   .prof ileContent   {   text-align : right;  margin : Opx; } 
.subtitle    {    text-align : right;    border-bottom: lpx  solid 
#ECEFF5;  color:#444444; 

margin: Opx  Opx  5px  Opx;   padding :2px  8px;  } 

7.6  Creating  info  sections 

Add  a  call  to  a  new  function,  updatelnf  oSection  ( )  in  your  index.php  and 
index jframe.php  files,  just  after  updateProf  ileBox  ( ) : 
updatelnf oSection (  $f acebook->user  ); 

Create  a  new  file  called  info.inc  in  the  inc  directory,  and  add  the  following 
source  code: 

<?php 

function  updatelnf oSection ( $appUserID)  { 
global  $g_categories  ; 
$db  =  new  DB ( ) ; 

$infoData  =  $db->getFeedbacksForUser ( $appUserID)  ; 
$facebook  =  new  Facebook (FB_API_KEY,   FB_APP_SECRET) ; 
$uids  =  array_keys ($inf oData)  ; 
$uids[]   =  $f acebook->user  ; 
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$users  =  array (); 

$userNames  =  $f acebook->api  client->users  getlnf o ($uids, 
' name ' ) ; 

foreach   ($userNames  as  $user)  { 
$users [$user [ 'uid' ] ]   =  $user [ ' name ' ] ; 
} 

$FeedbackInf oFields  =  array () ; 
foreach (   $infoData  as  $Feedback  )  { 
$FeedbackInf oFields [  ]    =  array ( 

'label'=>  $users [ $Feedback [ "targetID" ] ] . '   is  '. 
$g_categories [$Feedback [ "category" ] ] ["title"] , 
' image '   =>  L0CAL_APP_URL . " / img/ "  . 
$g_categories [$Feedback [ "category" ] ] ["bigimg"], 
'sublabel'  =>  '  Sent  by  ' . $users [ $Feedback [ "appUserlD" ] ]  , 
' description ' =>   'because    '. $Feedback [ "Feedback" ] , 
'link'=>   FB_APP_URL   ) ; 
} 

$inf oFields  =  array ( 

array (' field '     =>     'Feedbacks     Received',      'items'  => 
$FeedbackInf oFields) 
)  ; 

$f acebook->api_client->prof ile_setlnf o (    'Feedbacks',  5, 
$inf oFields, 
$appUserID  ) ; 

} 

?> 

This  file  now  contains  all  the  code  needed  to  create  the  content  for  our  info 
sections  and  update  them  on  Facebook.  Next,  add  this  statement  to  the  top 
of  index.php  and  index  iframe.php  files  to  include  this  new  file:  require_once 
'inc/info.inc'; 

Just  like  the  Add  to  Profile  buttons  we  previously  added,  we  need  to 
update  our  canvas  pages  to  display  the  Facebook-provided  Add  to  Info 
button.  If  its  an  FBML  canvas  page,  add  the  following  code  under  the 
addbutton  <div>  in  index.php: 

<div  id= ' inf obutton ' > 

<fb : if-section-not-added  section= ' info ' > 
<fb : add-section-button  section= ' inf o '  /> 
</ fb: if-section-not-added> 
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</div> 

If  its  an  IFrame,  add  the  following  line  for  the  new  infobutton  placeholder 
<div>  after  the  addbutton  placeholder  <div>  in  index  iframe.php: 

<div  id= ' infobutton ' ></div> 

Also,  add  this  line  right  after  the  showAddSectionButton()  call  for  the 
Profile  button  in  index  iframe.php: 

FB  .  Connect  .  showAddSectionButton ( ' info ' , document . 
getElementByld ( ' infobutton ' ) ) ; 

Finally,  you  need  to  add  the  following  line  to  main.css  to  position  the 
button  in  the  banner: 

#infobutton  {  position : absolute;  top:48px;  right :33px;  } 

7.7  Managing  the  FBML  Cache 

FBML  for  profile  boxes  are  cached.  This  works  fine  with  applications  with 
completely  static  content.  But  you  might  want  to  update  a  user's  profile  boxes 
when  he/she  accesses  the  application  to  reflect  the  most  current  information. 
If  you  want  to  update  many  of  your  users'  profile  boxes  at  once  because  of 
a  general  style  change  or  content  change  that  applies  to  a  large  set  of  users, 
you  can  simply  to  set  up  a  server-side  cron  job  to  iterate  through  all  the 
application's  users  and  call  profile .  setFBML  ( )  for  them.  However,  if  your 
application  has  a  large  number  of  users,  this  can  take  forever  to  accomplish, 
and  be  unmanageable.  For  this  very  reason,  Facebook  provides  you  the 
<fb :  ref  >  FBML  tag  can  mark  blocks  of  FBML  that  can  be  updated  across 
many  profiles  with  a  single  call.  There  are  two  ways  in  which  you  can  use 
this  tag:  by  URL  and  by  Handle.  They  both  eventually  achieve  the  same 
result,  but  one  might  fit  better  with  your  application  design  than  the  other. 
If  you  specify  a  URL,  Facebook  calls  that  URL  to  get  the  new  content  when 
the  cache  is  being  refreshed,  while  if  you  specify  a  Handle,  your  application 
directly  passes  the  new  FBML  content.  The  <fb:ref>  tags  can  also  be 
nested,  but  only  the  content  of  the  Handle  or  URL  specified  is  updated. 

Let  us  see  how  an  application  might  use  <f  b :  ref  >  with  a  Handle.  Create 
a  block  of  FBML  and  pass  it  to  fbml .  setRef  Handle  ( )  with  a  unique 
Handle  identifier.  Then,  use  <fb:  ref  handle='  youridentif  ier  '  />  in 
your  profile  FBML  content  wherever  you  want  that  block  of  FBML  to  appear 
and  pass  it  to  profile.  setFBML  () .  After  this,  your  application  can  just 
call  fbml .  setRef  Handle  ( )  with  new  FBML  to  update  all  profiles  that 
contain  that  Handle  to  use  the  new  content.  Only  the  section  in  the  Handle 
will  be  updated. 
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$commonFBML  =  "<div>This  month's  theme  is  xxxxx</div>" ; 
$facebook->api_client->fbral_setRef Handle (" temp "  , 
$  commonFBML ) ; 

$profileFBML  =  " 
<div> 

<hl>Theme</hl> 

<fb:ref  handle= ' temp ' /> 

</div>"; 

$f acebook->api_client->prof ile_setFBML (NULL,  $appUserID, 
$prof ileFBML, 

NULL,    NULL,  NULL); 

You  can  also  do  the  same  thing  by  using  a  URL  and  not  setting  the  cache 
the  FBML  ahead  of  time.  Instead,  supply  a  callback  URL  from  which  the 
FBML  can  be  retrieved.  Call  fbml.refreshRefUrl()  and  pass  the  URL  to 
update  it.  The  callback  will  return  the  FBML,  and  will  only  be  called  one 
time,  not  once  per  profile  updated. 

$profileFBML  =  " 

<div> 

<hl>This  month's  theme</hl> 

<fb : ref  url= ' http : // thinkdigit . com/ theme/ > 

</div>"; 

$f acebook->api_client->prof ile_setFBML (NULL,  $appUserID, 
$prof ileFBML, 

NULL,    NULL,  NULL); 

$  f acebook->api_cl ient->f bml_re f reshRef Ur 1  (  "http : / / 
thinkdigit server . com/ get theme .php" ) ; 

Modify  the  code  for  $formBlock  in  the  renderPage()  function  in  profile, 
inc  to  use  <fb:ref>  for  the  categories  list  and  to  update  the  list  of  available 
categories  to  all  of  our  users  at  once: 

$formBlock  =  " 

<div  class= ' sendFeedback ' > 

<span  class= ' sendTitle ' >Send  FeedBack</span> 
<form  method='POST'   id= ' FeedbackForm'   action= ' " . FB_APP_ 
URL. "/ '> 

<div  class= ' categories ' > 

<fb : ref  handle= 'prof ileCategories ' /> 

</div> 

<input  type= ' hidden '   name= ' target '   value= ' $appUserID ' /> 
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<input  class= ' textlnput '   name= ' Feedback ' /><br/> 
<input  class= ' inputbutton  '  type= ' submit ' 

name= ' submitFeedback ' 
value= ' Send ' > 
</ f orm> 
</div>"; 

Let's  now  create  a  new  updateCategoriesRef()  function  that  will  generate 
the  FBML  for  the  categories  and  stores  it  in  a  <fb:ref>  handle, 
function  updateCategoriesRef ( ) { 
global  $g_categories ; 

$facebook  =  new  Facebook (FB_API_KEY,   FB_APP_SECRET) ; 
$categories  =  ""; 

f oreach (   $g_categories  as  $name  =>  $info  ){ 

$categories  .=" 

<div  class= ' category ' > 

<img  class= ' categorylmg '   title= '{ $info [' title ']} ' 

src=' " .LOCAL_APP_URL. "/img/" . $info[ ' smallimg' ] . "' /><br> 

<div  class='categoryTitle'>{$info[ 'title' ] }</div> 

<input  type=' radio'   name= ' category '  value= ' $name '  /> 

</div>"; 

} 

$categories   .=  "<div  style= ' clear :both; ' ></div>" ; 
$f acebook->api  client->fbml_setRef Handle ( "prof ileCatego 
ries",    $categories) ; 
}  □ 


thinkd\9\t 


73 


FAST  TRACK-  APRIL  2010 


Win!! 

Exciting  Prizes 
worth  Rs.20000 

What  you  learn  from  this  Fast  Track  could  win 
you  Rs.  20,000  in  exciting  prizes.  Take  part  in 
Digit's  Facebook  Apps  contest  by  going  to 

www.thinkdigit.com/d/fb_contest 


□  Feed  stories 


Facebook  provides  different  ways  for  its  applications  to  communicate  and 
interact  with  its  users  and  their  friends.  Basically,  there  are  several  ways 
to  create  and  publish  Feed  stories,  get  them  published  to  the  stream  and 
manage  the  story  templates  using  both  the  Facebook  tools  and  the  API. 
There  are  three  APIs  to  publish  mini  feeds  and  news  feeds.  But  all  of  them 
are  restricted  to  call  not  more  than  10  times  for  a  particular  user  in  a  48  hour 
cycle.  This  means  you  can  publish  a  maximum  of  10  feeds  in  a  specific  user's 
profile  in  48  hours: 

feedpublishStoryToUser— The  method  used  to  publish  a  story  to  the 
news  feed  of  any  user  (limited  to  call  once  every  12  hours). 

feed  publishActionOfUser— The  method  used  to  publish  the  story  to  a 
user's  mini  feed,  and  to  his  or  her  friend's  news  feed  (limited  to  call  10  times 
in  a  rolling  48  hour  slot). 

feed  publishTemplatizedAction— the  method  used  to  publish  mini  feeds 
and  news  feeds,  but  in  an  easier  way  (limited  to  call  10  times  in  a  rolling  48 
hour  slot). 

You  can  test  this  API  from  http://developers.facebook.com/tools.php?api  by  choosing 
Feed  Preview  Console. 

8.1  Feed  forms 

Facebook  Feed  Form  is  the  most  basic  method  of  publishing  content  on 
Facebook.  We  will  start  by  creating  a  control  that  submits  Feed  stories  to  the 
stream.  All  you  need  to  do  to  convert  a  normal  HTML  form  into  a  Facebook 
Feed  form  is: 

<form  method= ' POST '  f btype= ' multiFeedStory  ' 

id= ' f eedbackf orm ' 

action=' " . LOCAL_APP_URL . " f eed_f orm_callback . php '  > 
<hl>Select  one  of  the  readers  and     your  feedback . </hl> 
<input  class= ' inputbutton  '  type= ' submit ' 

name= ' submitFeedback ' 

label='Send  Feedback'  value='Send  Feedback' /> 
</ f orm> 

The  major  change  required  here  is  that  Feed  forms  should  have  an  action 
attribute  set  to  an  absolute  URL.  In  our  case,  it's  been  set  to  the  full  URL  of  a 
new  file,  feed  form  callback.php.  Also  we've  added  the  fbtype  attribute  to  the 
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form  tag.  This  makes  Facebook  to  treat  this  form  as  a  Feed  form  and  publish 
its  data  to  the  stream. 

As  of  now,  there  are  two  types  of  Feed  forms:  f  eedStory  and  multi  Feed- 
Story.  To  create  a  feedStory  form,  you  need  to  set  the  form's  fbtype 
attribute  to  feedStory  and  to  create  multiFeedStory  form,  you  need 
to  set  it  to  multiFeedStory.  Although  the  differences  between  them  are 
minor  syntactic,  the  way  they  behave  is  completely  different.  The  feedform 
publishes  content  to  the  current  user's  Wall  and  their  friends'  News  Feeds, 
whereas  the  multiFeedStory  form  publishes  it  to  both  the  Wall  of  the 
current  user  and  one  of  his  friends.  For  this  reason,  the  multiFeedStory  form 
also  requires  an  FBML  <fb:  f  riend-selector>  tag  to  be  placed  on  the 
form  to  allow  the  user  to  choose  to  which  of  their  friends'  Walls  they  want  to 
publish  the  content.  Targeting  multiple  friends  is  not  yet  supported. 

feed  publishTemplatizedAction  is  yet  another  API  to  publish  news  feed 
to  a  friend  of  the  users  of  your  application.  It  takes  a  number  of  parameters, 
and  all  the  rules  of  publisActionOfUser  are  affected  by  the  same  kind  of 
uncertainty  and  delay  that  is  encountered  while  publishing  the  feed: 

title  template  -  A  template  which  contains  the  title  of  the  feed 

title  data  -  A  JSON  encoded  string  containing  the  value  of  the  template 
variables 

body  template  -  A  template  containing  the  text  of  the  body 
body  data  -  A  JSON  encoded  string  containing  the  value  of  the  template 
variables 

body  general  -  Additional  template  data  to  include  in  the  body 
image  1  -  The  URL  of  an  image  to  be  displayed  in  the  Feed  story 
image  1  link  -  The  URL  destination  after  a  click  on  the  image  referenced 
by  image  1 

image  2  -  The  URL  of  an  image  to  be  displayed  in  the  Feed  story 
image  2  link  -  The  URL  destination  after  a  click  on  the  image  referenced 
by  image  2 

image  3  -  The  URL  of  an  image  to  be  displayed  in  the  Feed  story 
image  3  link  -  The  URL  destination  after  a  click  on  the  image  referenced 
by  image  3 

image  4  -  The  URL  of  an  image  to  be  displayed  in  the  Feed  story 
image  4  link  -  The  URL  destination  after  a  click  on  the  image  referenced 
by  image  4 

target  id  -  Comma-delimited  list  of  IDs  of  friends  of  the  actor,  used  for 
stories  about  a  direct  action  between  the  actor  and  these  targets  of  his/her 


FAST  TRACK -APRIL  2010 


76 


thinkd\9\t 


Creating  Facebook  Apps 


Feed  stories  D 


action.  This  is  required  if  either  the  title_template  or  bodyjemplate  includes 
the  token  {target}. 

It  can  publish  up  to  four  images  in  the  feed.  If  you  want  to  make  them 
clickable,  supply  the  destination  URL  along  with  them.  The  following  code 
snippet  shows  you  how  to  use  this  API: 

<?php 

$titleTemplate  +  "{actor}  gifts  an  {item}  to  {friend}"; 
$titleData  =  array  (" item"=>"f lower ", "friend"=>"<fb : name 
uid='some  uid'>"); 

$bodyTemplate  =  "color  of  that  {item}  is  {color}"; 
$bodyData  =  array ( "color"=>"red" ," item"=>"f lower ")  ; 
$imagel  =  "absolute  url  of  an  image"; 

$imagelTarget  =  "target  url  when  clicked  over  that 
image" ; 

$f acebook->api  client->feed  publishTemplatizedAction  ( $ 
titleTemplate, j  son_encode ( $titleData) , $bodyTemplate, j  son_ 
encode ($bodyData) , $imagel, $imagelTarget) ; 

?> 

8.2  Publisher 

Facebook  offers  several  communication  channels  for  applications  and  their 
users  that  can  greatly  expand  an  application's  reach  within  the  Facebook 
social  graph,  and  ultimately,  its  potential  for  success,  the  basic  being 
interacting  with  and  producing  content  for  the  Facebook  stream  via  Feed 
forms  and  the  Facebook  application  programming  interface  (API).  Another 
novel  way  for  application  users  to  publish  content  to  the  stream  is  via  a 
special  construct  known  as  the  Publisher  which  is  more  closely  associated 
with  an  application  user's  profile  and  Home  page  than  it  is  with  an 
application.  It  allow  your  application  users  to  insert  new  application  content 
directly  and  immediately  to  the  stream  without  having  to  leave  their  profile 
or  Home  page.  Your  Applications  can  register  its  own  custom  Publisher,  and 
content  created  by  it  is  always  submitted  to  the  stream  in  short  story  Feed 
format.  It  can  even  contain  rich  media,  such  as  images,  audio,  or  video. 

There  are  several  notification  types,  lightweight  messages  sent  by 
applications  without  user  interaction;  which  are  one  of  the  most  powerful 
application  communication  mechanisms  available.  Finally,  we  delve  into 
requests,  which  are  one  of  the  more  controversial  and  misunderstood 
methods  of  application  messaging.  Requests  are  interesting,  because 
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they  encompass  one  of  the  most  direct  means  for  applications  to  spread: 
invitations.  You  use  all  of  your  new,  knowledge  to  update  your  sample 
application  to  use  these  features,  which  greatly  enhances  its  capabilities. 

The  Publisher  link  of  default  Facebook  applications  always  appear 
first  in  the  list,  followed  by  any  application  specific  ones  ordered  by 
how  recently  they  were  used.  If  you  visit  a  friend's  profile,  you  see  his 
Publishers  arranged  in  an  order  that  reflects  the  applications  that  your 
friend  has  used.  If  you  click  inside  the  Publisher  box's  text  area,  it  expands  it 
to  show  all  the  applications  that  have  provided  Publisher  integration  for  the 
current  profile. 

Using  Publisher,  applications  can  present  their  own  custom  interactive 
interfaces  for  creating  Feed  content  that  are  not  subject  to  the  same  constraints 
that  Facebook  imposes  on  other  application  interaction  points,  such  as  profile 
boxes  or  application  tabs.  Your  application  can  automatically  play  Flash 
videos  or  even  hook  the  onload()  event  in  Facebook  JavaScript  (FBJS). 

Feed  forms  are  specialised  FBML  forms  that  exist  on  application-specific 
canvas  pages  or  application  tabs.  Facebook  handles  Feed  forms  in  a  way  that 
client-side  form  validation  is  impossible.  However,  a  Publisher  interface  has 
no  such  restrictions.  A  Publisher  can  use  FBJS  directly  to  dynamically  enable 
a  form's  Submit  button,  depending  on  the  state  of  the  form's  data  or  variables. 
When  the  application  users  employ  the  Publisher,  they  don't  have  to  visit 
the  application-specific  page  to  publish  application  content.  A  Publisher 
can  directly  insert  content  into  the  Home  page  News  feed  and  the  Wall 
simultaneously  and  instantaneously.  As  soon  as  user  submits  a  Feed  story 
from  a  Publisher  to  his  own  profile  or  Home  page,  a  short  Feed  story  is  created 
in  both  locations  along  with  the  Home  page  News  feed  of  all  of  their  friends. 

8.3  Integrating  with  the  publisher 

Applications  that  provide  publisher  interfaces  can  provide  two  separate 
integration  points: 

•  The  first  integration  point  used  for  publishing  content  to  a  user's 
own  profile 

•  The  second  for  publishing  to  friends'  profiles. 

Because  Publishers  are  not  required  by  the  platform,  applications 
can  supply  integration  points  for  neither,  one,  or  both.  We'll  update  our 
application  to  provide  both  for  illustrative  purposes.  We'll  refer  to  the 
first  flavour  of  Publisher  as  a  Self-Publisher  and  the  second,  as  an  Other- 
Publisher. 
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8.4  Publisher  developer  settings 

To  get  started  with  Publisher,  you  first  have  to  go  to  your  application's 
Developer  Settings  page  (www.facebook.com/developers/apps.php),  choose  your 
application  from  the  list  on  the  left  and  then  click  on  Edit  Settings.  Go  to 
the  Profiles  tab  and  look  for  the  section  titled  Profile  Publisher.  The  options 
here  are  used  to  specify  the  text  for  the  links  used  to  activate  the  Publishers 
and  the  URLs  from  which  Facebook  will  pull  their  content.  For  the  Publish 
Text  value,  enter  the  name  of  the  application,  i.e.,  Compliment.  For  the 
Publish  Callback  URL,  enter  something  like  http://example.com/<application_name>/ 
publisher_callback.php,  but  be  sure  to  use  your  own  local  URL.  If  you  decide  to 
use  different  values  for  the  link  labels,  make  sure  its  less  than  20  characters. 

8.5  Creating  the  publisher 

Once  you  have  set  the  necessary  options  in  your  applications'  Developer 
Settings,  you  can  actually  implement  the  Publisher.  Facebook  communicates 
with  the  application  when  using  a  Publisher  by  actually  requesting 
information  from  the  Publisher  Callback  URLs  on  two  separate  occasions: 

•  When  a  user  clicks  a  Publisher  link  in  a  profile  or  Home  page,  Facebook 
makes  calls  to  request  the  FBML  and  display  the  Publisher. 

•  If  a  user  then  submits  a  story  from  that  Publisher,  Facebook  calls  it  again 
to  request  the  content  for  the  Feed  story  it  has  to  publish.  Your  callback's 
code  determines  which  type  of  request  Facebook  makes  by  checking  the 
value  of  the  method  POST  variable,  which  Facebook  sends  with  each  call. 

The  five  POST  variables  sent  by  Facebook  that  you'll  come  across  when 
creating  Publishers  are: 

fb  sig  user  -  Facebook  ID  of  user  interacting  with  the  Publisher.  It  is 
always  sent. 

fb  sig  profile  user  -  Facebook  ID  of  user  from  whose  profile  the  Publisher 
was  requested.  It  is  always  sent. 

fb  sig  session  key  -  If  sent,  it  means  the  user  identified  by  fb  sig  user  has 
authorized  the  application  that  provided  the  Publisher. 

app  params  -  Contains  an  array  of  the  Publisher's  form  variable  data, 
keyed  by  form  element  name.  It  is  only  sent  when  method  has  the  value 
publisher  getFeedStory. 

Now  that  you  can  determine  if  the  values  of  fb  sig  user  and  fb  sig  profile 
user  are  equal,  it  is  certain  that  the  user  interacting  with  the  Publisher  is 
also  the  owner  of  the  profile  (or  Home  page)  from  which  it  was  launched; 
we  therefore  need  to  display  the  Self-Publisher  to  allow  this  user  to  publish 
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a  Feed  story  to  his  own  Wall  and  Home  page  News  feed.  If  these  values 
were  to  be  different,  you  should  display  the  Other-Publisher,  which  allows 
publishing  to  the  Wall  of  the  user  identified  by  fbsigprof  ileuser  and 
his/her  friends'  Home  pages.  If  you  want  the  Publisher  to  offer  enhanced 
functionality  to  users  that  have  authorised  the  application  that  provides 
it,  you  can  check  for  the  existence  of  fb  sig  session  key  in  the  POST 
variables  which  is  only  sent  when  this  is  true. 

Create  a  new  file  named  publisher  callback.php  in  your  application  root 
directory.  The  core  behaviors  of  both  displaying  a  custom  Publisher  and 
publishing  a  story  to  Facebook  are  shown  in  the  following  code  block  which 
you  need  to  add  to  publisher  callback.php. 

<?php 

require  once   ' inc/globals . inc ' ; 

require  once   '  inc/utils . inc ' ; 

require  once   ' inc/db . inc ' ; 

require  once   ' inc/prof ile . inc ' ; 

require  once   ' inc/notif ications . inc ' ; 

$fb  =  new  Facebook (FB_API_KEY,    FB_APP_SECRET) ; 

$publisher  =  $fb->user   ||    $f b->fb_params [ ' page_id '  ]  ; 

$target  =  $fb->fb_params [ 'prof ile_user ' ] ;  // 

$isSelfPub  =  $publisher  ===  $target; 

$publisherAction  =  $_POST [ 'method' ] ; 

$fbResponse  =   ' ' ; 

if(   isset(   $publisherAction  )  && 

isset  (  $publisher  )  && 

isset  (  $target  )    )  { 

if (    'publisher  getlnterf ace '   ===  $publisherAction  )  { 
$markup     =    getPublisherUI ($isSelfPub     ?     $publisher  : 
$target) ; 

$fbResponse  =  array (  ' content '=>  array (  ' f bml '  => 
$markup,  'publishEnabled'  =>  true  ),  'method'  => 
$publisherAction   ) ; 

}  else  if  (  'publisher  getFeedStory '  ===  $publisherAction 
)  { 

$formValues  =  $  POST['app  params ' ] ; 
if(   isset (   $formValues  )    )  { 
global  $g_categories  ; 

if  (  !  isset ( $f b->fb_params [ ' page_id '  ]  )  )  { 
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$db  =  new  DB  ( ) ; 

$db->addCompliment (  $publisher,  $isSelfPub  ?  $publisher  : 
$target,  $formValues [' category ']  ,  $formValues [' compliment '  ] 
)  ; 

} 

$categoryInf o  =  $g_categories [ $formValues [' category ']] ; 
$imageSrc  =  L OC AL_ AP P_U RL . ' / 

img/ ' . $categoryInf o [ 'bigimg ' ] ; 
$imageLink  =  LOCAL_APP_URL; 

$images  =  array (' src ' =>  $imageSrc,  'href'=>  $imageLink) ; 
$feed  =  array (    ' template_id'  => 

$isSelfPub  ?  TEMPLATE_BUNDLE_SELF_PUBLISH_1  :  TEMPLATE_ 
BUNDLE_0THER_PUBLISH_1,  ' template_data '  =>  array (  ' app '  => 
'<a  href=" ' .FB_APP_URL.    '">Compliments</a> ' , 

'ctitle'   =>  $categoryInf o [' title ']  , 

' ctext '   =>  $formValues [' compliment ']  , 

'images'   =>  array (  $images   )    )    ) ; 

}   else  { 

$fbResponse  =  getPublisherError (' Incorrect  method 
requested:  Expected  either  publisher  getFeedStory  or 
publisher  getlnterf ace ' ) ; 

} 

$fbResponse  =  array (    'method'   =>  $publisherAction, 
'content'   =>  array (    'feed'   =>  $feed  )    ) ; 
}   else  { 

$fbResponse    =    getPublisherError ( 'Missing    form  values 
from  Publisher ' ) ; 
} 

}   else  { 

$fbResponse  =  getPublisherError (' Either  method,  user,  or 
target  are  not  specified'); 
} 

echo  j sonencode ($fbResponse ) ; 
?> 

You  are  calling  the  getPublisherError  ( )  function  to  create  arrays  that 
Facebook  uses  to  notify  your  users  of  specific  error  conditions.  You  must 
also  provide  Facebook  with  a  JSON-encoded  associative  array  containing 
three  keys:  errorCode  (which  must  always  be  set  to  1,  handily  defined 
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by  the  constant  FACEBOOK_API_ VALIDATION  ERROR),  errorTitle,  and 
errorMessage.  The  values  for  errorTitle  and  errorMessage  are  used  to 
populate  the  error  dialog's  title  and  body  content,  respectively.  Add  the 
following  code  block  to  the  end  of  publisher  callback.php  to  achieve  that: 

function  getPublisherError ( $msg)  { 

return  array (  'errorCode'  =>  FACEBOOK_API_VALIDATION_ 
ERROR, 

'errorTitle'   =>   'Facebook  Publisher  Error', 

' errorMessage ' =>  $msg  ) ; 

} 

You  are  using  the  getPublisherUIO  function  to  provide  the  markup  for 
the  Publisher's  user  interface,  which  Facebook  requests  after  sending  the 
publisher  getlnterface  POST  variable.  getPublisherUIO  uses  the  getCSSO 
function  to  provide  the  styles  for  the  Publisher.  Add  the  following  code  block 
to  the  end  of  publisher  callback.php. 

function  getCSS ()  { 

$css  =  " 

<style> 

hi  {  font-size:  14px;  font-weight :bold;  text-align : center ; 
margin-top : 6px; 

margin-bottom: 6px;  } 

.panel     {     text-align: center;    background-color : #F7F7F7 ; 

padding: lOpx  0;} 

#complimentTable  {  margin:   5px  auto;  } 
#complimentTable   . textlnput  {  width:   85%;  } 
#complimentTable  td  {   text-align : center ;  } 
.category  {   float:left;   height:75px;   text-align : center ; 

margin :8px;  } 

.category  img   {  width: 48px;   height: 48px;  } 

.category  . categoryTitle  {  height:20px;  font-weight : bold; 

} 

</style>"; 
return  $css; 
} 

function  getPublisherUI (   $uid  )  { 
global  $g_categories  ; 
$out  =  getCSS () ; 
$out   .=  " 
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<div  class= 'panel ' > 
<f orm> 

<table  id= ' complimentTable ' > 

<tr> 

<td> 

<fb:if-is-friends-with-viewer  uid='$uid' 
include self = ' false ' > 
<hl> 

<fb:  name  uid= ' $uid '  f irstnameonly= ' true '  linked= ' false ' /> 
is : 

</hl> 

<fb:else> 

<hl> 

<fb:name  uid='$uid'  capitalize= ' true '  linked= ' false ' /> 
are : 

</hl> 

</fb :else> 

</ fb : if-is-f riends-with-viewer> 

</td> 

</tr> 

<tr> 

<td>"; 

foreach(   $g_categories  as  $name  =>  $info  ) { 
$out   .=  " 

<div  class= ' category ' > 
<img  class= ' catlmg ' 

src=' " .LOCAL_APP_URL . " /img/ { $ inf o [ 'bigimg' ] } ' /><br> 
<span  clas s= ' categor yTi tie ' > { $ inf o  [  ' t i t le ' ]  }</ 

span><br/> 

<input  type=' radio'   name= ' category '   value= ' $name ' /> 

</div>"; 

} 

$out   .=  " 

<div  style= ' clear : both; ' ></div> 

</td> 

</tr> 

<tr> 

<td> 
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<fb:if-is-friends-with-viewer  uid='$uid' 
includeself = ' false ' > 
<hl>because  they:</hl> 
<fb:else> 

<hl>because  you:</hl> 
</fb:else> 

</ f b : if-is-f riends-with-viewer> 

</td> 

</tr> 

<tr> 

<td> 

<input  class= ' textlnput '   name= ' compliment '  /> 

</td> 

</tr> 

</table> 

</ f orm> 

</div>"; 

return  $out; 

} 

There  are  sections  in  this  code  that  deal  with  responding  to  the  receipt  of 
the  method  variable  in  the  POST  variables  received  from  Facebook.  If  the 
value  of  method  is  publisher  getlnterface,  your  code  will  provide  Facebook 
with  a  specific  JSON  response  that  provides  it  with  the  raw  FBML  that 
comprises  the  Publisher's  user  interface,  as  follows: 

if (    'publisher  getlnterface'   ===  $publisherAction  )  { 
$markup     =    getPublisherUI ($isSelfPub     ?     $publisher  : 
$target) ; 

$fbResponse  =  array (  ' content '=>  array (  ' f bml '  => 
$markup, 

' publishEnabled '   =>  true  ), 
'method'   =>  $publisherAction  ) ; 
}  □ 
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Facebook  allows  your  application  user  to  invite  his  friends  to  use  that 
application,  which  acts  like  viral  marketing  in  spreading  your  application. 
So,  as  an  application  developer,  you  should  determine  when  and  how  to 
let  them  invite  their  friends  and  how  to  make  your  application  a  sure 
success  so  that  the  friends  of  your  application  user  also  pay  a  visit  to  your 
application.  You  can  also  let  their  user  send  email  notifications.  Let's  get 
started  on  creating  a  successful  invitation  and  notification  system  for  your 
application,  something  which  uses  these  constructs  efficiently  and  help 
your  application  spread. 

9.1  Invitations 

Invitations  are  used  to  send  emails  to  friends  of  a  user  of  that  application 
in  Facebook  applications,  using  which,  any  one  of  his  or  her  friends  can 
subscribe  to  your  Facebook  application.  This  is  a  great  way  of  promoting 
your  application. 

Until  sometime  back,  users  of  your  application  could  to  send  invitations 
to  all  their  friends  at  a  time,  but  recently  Facebook  added  some  strict 
policies  such  as,  a  user  can  invite  only  20  of  his/her  friends  each  day  and 
so  you  have  to  design  the  whole  system  using  Facebook  API,  or  the  default 
widget  provided.  An  invitation  system  on  Facebook  has  several  parts.  The 
FBML  tags  used  to  create  an  Invitation  system  are: 

•  fb:request-form 

•  fb:req-choice 

•  fb:request-form-submit 

•  fb:application-name 

•  fb:multi-friend-input 

•  fb:friend-selector 

•  fb:multi-friend-selector(condensed) 

However,  you  cannot  change  the  default  look  and  feel  of  this  one  unless 
you  use  CSS  style  sheets. 

9.1.1  fb:request-form 

This  tag  acts  as  the  primary  widget  for  inviting  friends  A  typical  invitation 
code  will  look  like: 

<fb: request-form 
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action=" invitation  processor  page" 

method="POST" 

invite="true" 

type="Application  Name" 

content="Content  of  your  Mail"> 

<f b : multi- friend- select or 

showborder=" false" 

actiontext=" Invite  friends  to  the  Application  Name" 
exclude  ids="exclude    friends    who    are    already  using 
this  app" 

max="20"  /> 

</ fb : request-f orm> 

The  various  parameters  for  this  FBML  tag  are: 

•  Action  -  This  parameter  supplies  the  information  as  to  where  the  page 
will  submit  all  the  information  when  someone  clicks  on  the  send  invitation 
or  skip  button. 

•  Method  -  This  parameter  is  used  to  select  GET  or  POST,  the  way 
information  will  be  submitted. 

•  Invite  -  It  can  be  true  or  false.  When  set  as  true,  the  invitation  will  go  as 
invitation,  otherwise  it  will  go  as  a  request.  This  change  actually  reflects  the 
content  of  the  invitation  that  the  user  will  get. 

•  Type  -  This  one  is  used  to  reflect  the  context  of  your  application.  It  is 
usually  set  the  same  as  the  application  name. 

9.1.2  fb:req-choice 

This  tag  is  used  to  insert  a  button  in  your  request  message,  and  define  the 
name  and  target  URL.  So  when  a  user  receives  your  invitation,  they  will  also 
see  this  button,  and  when  they  click  on  it,  they  will  be  redirected  to  the  URL 
that  you  have  specified.  This  is  very  useful  if  you  want  them  to  install  the 
application,  just  by  providing  a  nice  button  inside  your  invitation  message. 
The  various  parameters  for  this  FBML  tag  are: 

•  url  -  This  is  the  target  URL  which  used  to  redirect  the  user  on  a  click 
event. 

•  Label  -  This  is  just  the  caption  for  the  button. 
Example: 

<f b : req-choice  url="http : / / apps . facebook . com/ example/ 
Accept. php"   label="Accept"  /> 

Don't  use  "ignore"  as  the  caption  of  any  request  button  because  it  is  there 
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by  default.  So  if  you  insert  another  ignore  button,  the  code  will  not  work  and 
you  might  lose  all  the  other  buttons  inside  too. 

9.1.3  fb:request-form-submit 

This  tag  is  used  to  display  a  submit  button  inside  your  invitation  form.The 
various  parameters  for  this  FBML  tag  which  let  you  display  the  user's  name 
or  the  full  name  inside  this  button  are: 

•  uid  -  The  user  id  of  the  user  you  want  to  send  this  invitation  to. 

•  label  -  Used  to  provide  a  caption  to  the  button.  Tip  -To  show  the  first 
name  of  the  user,  use  %n  and  to  show  the  full  name,  use  %N. 

Example: 

<f b : request-f orm-submituid=  'some  uid'  label=  'send 
%N  an   Invitation'  /> 

9.1.4  fb:multi-friend-selector 

This  FBML  tag  is  used  to  draw  a  friend  selector  widget  anywhere  in  your 
canvas  page.  The  various  parameters  for  this  FBML  tag  are: 

•  actiontext  -Used  to  specify  what  to  display  at  the  top  of  this  friend 
selector  as  the  heading. 

•  showborder  -  Can  be  set  to  true  or  false. 

•  rows  -  Used  to  specify  the  number  of  rows,  that  friends  will  be  shown  in. 
The  default  value  is  S.  But  you  can  choose  anything  from  3  to  10. 

•  max  -  Used  to  specify  the  maximum  number  of  friends  a  user  can  select 
at  a  time  to  send  an  invitation  to.  It  is  advisable  to  keep  it  at  20  because  of 
Facebook  regulations. 

•  excludejds  -  This  is  a  comma  separated  list  of  friends  who  are  not  to  be 
shown  inside  this  selector  object.  Use  this  to  exclude  all  your  friends  who 
have  already  installed  this  application. 

•  bypass  -  Used  to  add  a  label  to  the  skip  button. 

•  condensed  -  If  set  to  true,  it  will  create  a  condensed  page  that  looks  far 
different  from  a  full  version. 

9.1.5  fb:multi-friend-input 

Instead  of  using  a  multi-friend  selector  in  your  Invitation  system,  you  can 
also  use  a  multi-friend  input  in  a  fb:request-form,  although  it  is  much  less 
user-friendly  as  compared  to  a  friend  selector.  The  usage  of  multi-friend 
selector  is  very  simple  and  you  can  select  an  arbitrary  numbers  of  friends. 
The  various  parameters  for  this  FBML  tag  are: 
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•  width  -  Used  to  specify  the  width  of  the  input  box. 

•  border_color  -  Used  to  enter  the  HTML  colour  code  to  colour  the  border 
of  this  selector  panel. 

•  include_me  -  If  this  is  set  to  true,  the  user  can  select  himself/herself.  By 
default,  it  is  obviously  set  to  false. 

•  max  -  Used  to  specify  the  maximum  number  of  friends  a  user  can  select 
at  a  time  to  send  an  invitation  to.  It  is  advisable  to  keep  it  at  20  because  of 
Facebook  regulations. 

•  excludejds  -  This  is  a  comma  separated  list  of  friends  who  are  not  to  be 
shown  inside  this  selector  object.  Use  this  to  exclude  all  your  friends  who 
have  already  installed  this  application  and  they  will  be  excluded  from  the 
auto  drop-down  box. 

•  prefilHds  -  This  is  a  comma  separated  list  of  friend  ids,  who  will  be 
selected  automatically  whenever  this  box  is  viewed. 

•  prefilljocked  -  If  this  is  set  to  true,  the  user  cannot  remove  the  prefilled 
friends. 

Example: 

< fb : mul ti - fr iend- input        width=" 3 0 Opx"  border 
color="#000"   exclude_ids=" some  id,    another  id"  /> 

You  might  want  to  manage  the  data  that  the  user  inputs.  This  can 
be  possible  because  if  your  form  contains  multi-friend  input;  once  it  is 
submitted,  you  will  find  all  the  IDs  of  the  selected  friends  in  $  POST['ids'] 
or  $_GET['ids'] 

9.1.6  fb:application-name 

This  FBML  tag  is  used  to  easily  define  the  name  of  your  application, 
especially  when  it  contains  some  restricted  words  in  it,  such  as  "message". 
Facebook  limits  the  usage  of  these  restricted  words  when  invitations  go  to 
news  feed  and  mini  feed,  so  you  need  to  use  fb:application-name  to  rescue 
them. 

Example: 

<f b : application-name> 

Message  builder 

</ fb : application-name> 

9.2  Notifications 

There  are  two  ways  of  sending  notifications  to  your  users:  By  using  the 
Notify  page  or  by  an  email.  Sending  notifications  to  the  notification  page 
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of  a  user  does  not  require  confirmation  from  the  specific  user.  So  you  can 
use  this  to  send  information  about  the  activity  of  their  friends  who  are  also 
users  of  your  application  to  them.  You  can  also  send  notification  to  non- 
users  of  your  applications,  but  it  can  be  classified  as  spam.  There  are  two 
functions  in  the  Facebook  REST  API  useful  for  sending  notifications: 

•  notifications  send 

•  notifications  sendEmail 

9.2.1  notifications_send 

This  function  is  used  to  send  notifications  to  the  user's  notifications 
page,  located  at  http://www.facebook.com/notifications.php.  The  following 
source  code  sends  invitations  to  your  application. 

<?php 

include  once ( "prepend . php" ) ; 

$facebook->api  client->notifications 
send (array ( 5032 74 632 )," This     is     a     sampleNotif ication 
from  Digit  Sample  App"); 

?> 

This  function  has  two  parameters  :  an  array  of  users  to  whom  you  want 
to  send  notifications  and  a  text  block,  which  can  contain  only  text  and  links. 

9.2.2  notifications_sendEmail 

This  function  is  used  to  send  notifications  to  a  user's  mailbox,  instead  of 
the  notification  page.  But  remember  that  Facebook  allows  you  to  send  only 
a  maximum  number  of  5  emails  per  user,  per  day.  This  also  needs  the  user's 
permission  before  you  finally  dispatch  the  mail.  Let's  take  a  look: 

<div  style="padding : 2 Opx; "> 
<?php 

if    (empty ($_POST [' ids '])) { 
?> 

<form  method="POST"> 

Select  Some  friends  whom  you  want  to  send  an  Email. 
< fb : mul ti - fr iend- input        width=" 3 0 Opx"  border 
color="#000"   include  me='true'   exclude  ids=""  /><br/> 
Type  your  message  to  them<br/> 
<textarea  name  =' email  '></ textareaxbr /> 
<input  type= ' submit '   value='Send  Mail'  /> 
</ f orm> 
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<? }  ?> 

</div> 

<div  style="padding : 20px; "> 
<?php 

include  once ( "prepend. php" ) ; 
if    (! empty ($_POST [' ids '])) { 
$email  =  $_POST [' email '] ; 

$successful    friends=  $ f a cebo o k- > ap i  client- 

>notif ications_sendEmail ($_POST [' ids '] , "This  is  a 
sample  Mail  from  Facebook  Application  Development 
Book" , $ email , $ email ) ; 

echo  "Emails  successfully  sent  to  the  following 
friends  <br/>"; 

$parts  =  explode (",",$ successf ul_f r iends ) ; 

f oreach ( $parts  as  $part) 

echo  "<f b : nameuid= ' { $part } '  useyou= ' false '  /></br>"; 
} 

?> 

</div> 

This  function  has  four  parameters: 

•  An  array  of  users  whom  you  want  to  email. 

•  The  subject  of  the  email. 

•  The  content  in  plain  text. 

•  The  content  in  HTML. 

This  function  also  returns  a  comma  separated  list  of  all  successful 
recipients.  As  notification  and  emails  are  the  most  effective  way  of  keeping 
your  users  up  to  date  as  well  as  promoting  your  application,  you  should  use 
them  carefully  to  take  maximum  advantage  of  them.  Make  sure  you  catch 
the  most  interesting  moments  of  your  application,  and  ask  your  users  to 
send  emails  to  their  friends  before  it.  For  example,  if  you  have  created  a  quiz 
application;  after  displaying  the  result  to  your  user  who  has  taken  the  quiz 
just  now,  ask  them  to  compare  with  their  friends  and  display  an  invite  page. 
Most  of  the  users  will  invite  their  friends  in  such  a  case.  In  the  email  you  are 
sending,  you  can  send  the  score  of  that  user  and  challenge  him  to  compare 
which  makes  his  invitation  more  enticing.  Also  as  soon  as  someone  installs 
your  application,  show  them  an  invitation  page  before  they  dive  further. 
Keep  random  links  such  as  "Show  your  performance/score/Compare 
whatever  to  your  friends",  which  redirect  the  users  to  an  invitation  page 
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when  clicked.  Whenever  a  user  has  achieved  or  done  something  interesting, 
send  his  friends  some  notification  regarding  it.  It  generally  works  as  viral 
marketing.  You  can  keep  a  page  in  your  application,  where  a  user  can 
monitor  which  of  his  friends  also  use  it  and  track  the  activities  of  his  friends 
for  that  application.  It  all  depends  on  your  creativity.  0 
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Digit's 
Facebook  Apps 
Contest 

What  you  learn  from  this  Fast  Track  could  win 
you  Rs.  20,000  in  exciting  prizes.  Take  part  in 
Digit's  Facebook  Apps  contest  by  going  to 

www.thinkdigit.com/d/fb_contest 


EQ  Additional  Resources 


Now,  that  you've  started  and  built  your  application,  there  will  be  certain 
problems  you  will  run  into  while  implanting  the  various  features  we 
talked  about.  So.what  do  you  do?  The  single  best  resource  for  these  types 
of  problems  is  the  Facebook  Developers  forum  at  http://forum.developers.facebook. 
com/.  There's  also  a  channel  on  freenode  (#Facebook)  if  you're  old-school  and 
more  comfortable  on  IRC.  This  is  at  times  the  faster  way  to  get  an  answer  to 
a  specific  question.  You  can  also  check  out  the  different  Facebook  developer 
groups  (http://wiki.developers.facebook.com/index.php/Local_Developer_Group). 

Besides  these  are  are  several  good  references  for  Facebook  Developers: 

•  All  Facebook.  http://allfacebook.com 

•  Developer  News,  http://developers.facebook.com/news.php 

•  Facebook  News,  http://blog.facebook.com/blog.php 

•  Inside  Facebook.  www.insidefacebook.com 

•  Application  Verification  Program,  http://developers.facebook.com/verification.php 

•  Client  Libraries.  http://wiki.developers.facebook.com/index.php/Client_Libraries 

•  Custom  Tags  Directory.  http://wiki.developers.facebook.com/index.php/Custom_Tags_ 
Directory 

•  Developer  Application,  www.facebook.com/developers 

•  Developer  Wiki.  http://wiki.developers.facebook.com/index.php/Main_Page 

•  Developer  Forum,  http://forum.developers.facebook.com/ 

•  Developer  Test  Accounts,  www.facebook.com/developers/become_test_account.php 

•  Developer  Test  Consoles,  http://developers.facebook.com/tools.php 

•  Facebook  Open  Source,  http://developers.facebook.com/opensource.php 

•  fbFund.  http://developers.facebook.com/fbFund.php?tab=about 

•  Guiding  Principles,  http://developers.facebook.com/get_started. php?tab=principles 

•  Platform  Statistics.  www.facebook.com/press/info.php?statistics 

•  Terms  of  Service,  www.facebook.com/terms.php 

•  APC.  http://php.net/apc 

•  Firebug,  www.getfirebug.com 

•  Firebug  Lite,  http://getfirebug.com/lite.html 

•  Memcached.  www.danga.com/memcached 

•  Web  Developer  Toolbar,  http://chrispederick.com/work/web-developer 

•  YSlow.  http://developer.yahoo.com/yslow 

•  YUI  Library,  http://developer.yahoo.com/yui 
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10.1  Taking  your  application  further 

Facebook  platform  also  supports  various  resources  that  help  you  analyze 
your  application  statistics,  where  to  go  if  you  get  stuck,  and,  perhaps  most 
important,  how  to  generate  a  revenue  stream  from  your  application!  A  lot  of 
applications  generate  a  good  revenue  stream  from  advertisements  and  with 
some  planning  and  some  good  choices,  you  should  be  able  to  at  least  offset 
the  costs  of  your  server  hosting,  if  not  turn  into  a  millionaire. 

10.1.1  Application  Statistics 

There  is  a  basic  statistics  feature  in  the  Facebook  Developer  application  to 
help  you  get  an  idea  of  what's  going  on  with  your  application  by  giving  you 
detailed  stats  on  usage,  HTTP  status  requests,  and  recent  HTTP  requests. 
You  are  also  provided  with  a  helpful  User  Engagement  statistic  that  tells 
you  how  many  people  have  used  your  application  in  the  past  24  hours.  This 
helps  you  figure  out  how  many  people  are  actually  "using"  your  application. 

But,  if  you  need  or  want  more  sophisticated  statistics,  the 
<fb :  googleanalytics>  tag  comes  in  handy.  Create  an  account  on  Google 
Analytics  to  use  this  tag  and  it  will  provide  you  with  exceptionally  detailed 
statistics  about  your  application  (and  for  that  matter,  any  web  site  build). 
Navigate  to  http://www.google.com/analytics/  and  sign  in  with  your  Google  account  to 
use  Google  Analytics.  Add  a  web  site  profile  by  clicking  on  the  Add  Website 
Profile  link  to  start  the  process.  Next,  fill  out  the  form  for  a  new  domain 
using  your  server  address  URL  (not  your  http://apps.facebook.com/<your_app_name> 
URL)  and  click  on  continue.  You  will  now  be  presented  with  a  small  snippet 
of  JavaScript  to  add  to  your  page.  But  it's  not  FBJS.  So,  you  cannot  add  it 
directly.  Just  get  the  account  number  (defined  by  the  uacct  variable)  from 
that  code  to  use  the  <fb:  google-analytics>  tag,  and  let  Facebook  write 
this  in  for  you. 

Add  the  following  code  in  your  application  to  produce  the  required 
JavaScript  in  your  application: 

<f b : google-analytics      uacct="<your  UA  account  number>" 

/> 

Facebook  will  automatically  correct  and  add  the  JavaScript  to  the  resultant 
HTML  stream.  You  will  also  have  access  to  the  Google  Analytics  tracker  in 
FBJS  with  the  Facebook.urchinTracker  object  in  case  you  want  it.  <fb:google- 
analytics>  tag  is  the  easiest  way  to  implement  your  own  methods  through 
FBJS;  however,  if  you  should  you  need  more  granular  control  over  what  gets 
sent  to  the  Google  servers  for  your  application,  the  functionality  does  exist. 
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Google  Analytics  provides  you  with  a  really  great  statistics  set  including 
a  site  overlay,  geotargeting,  Google  AdWords  integration,  and  just  about  any 
other  type  of  useful  statistic  that  you  could  possibly  want  about  the  people 
using  your  application. 

10.1.2  Monetizing  your  application 

Facebook  has  several  service  agreements  which  allow  application 
developers  to  monetize  their  applications.  The  most  popular  among  them  is 
Google  Adsense. 

AdSense 

You've  already  set  up  a  Google  Analytics  account  in  the  previous  section. 
Now  to  enable  Google  Adsense  too,  all  you  need  to  do  is  -  go  to  the  AdSense 
web  site  at  http://adsense.google.com,  and  create  a  separate  AdSense  account  by 
clicking  on  the  Sign  Up  Now  button  (if  you  don't  already  have  an  account). 
Once  you've  set  up  an  AdSense  account  and  filled  out  the  appropriate  forms, 
you  get  the  option  to  decide  what  type  of  advertising  you  want  to  implement 
from  among  ads  for  content,  search,  referrals,  video,  and  mobile  content. 
Google  also  provides  you  with  some  other  options  for  your  ads  (text  and 
images  or  text  or  images  only),  size  and  color  palette  etc.  so  choose  carefully 
a  theme  that  matches  your  overall  application  design.  The  best  aspect  AdSense 
is  that  its  ads  are  generally  unobtrusive  and  can  be  placed  anywhere  on  a  page. 
There  are  also  nice  tools  for  tracking  your  earnings  and  growth  over  time. 

To  get  relevant  ads  from  Google,  you  first  need  to  make  your  canvas 
page  publicly  available  so  it  can  be  crawled  by  Google.  To  do  this,  just 
change  all  the  require  login  functions  in  the  application  to  the  get  loggedin 
user  function: 

$user  =  $f acebook->get_loggedin_user ( ) ; 

You  can  use  any  of  the  previously  used  canvas  page  tags  on  this  page 
without  any  changes  to  your  code,  although  you  should  refactor  some  of 
your  existing  code  for  non-logged-in  users. 

There  is  also  an  iframe  way  to  use  AdSense.  Make  a  new  page  that  contains 
the  JavaScript  that  Google  provides  you  when  you  generate  the  ads  for  your 
page  on  your  web  site,  and  then  call  that  page  through  the  <fb:iframe>  tag  on 
your  canvas  page. 

<fb : iframe  src="http : / /siteURL . com/ads ,php" 

width="<google_ad_width>" 

height="<google_ad_height>"  /> 
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This  is  the  code  snipped  you  need  to  insert  in  your  code  where  you  want 
to  place  the  ads  for  AdSense  to  work  properly  on  iFrame  pages. 
Some  others  ways  to  generate  revenue 

There  are  a  lot  of  other  services  to  generate  revenue  from  your  Facebook 
application.  Most  of  these  work  just  like  AdSense  and  leverage  their 
advertising  in  your  application.  Here  is  a  list  of  some  of  them  that  you  might 
want  to  check  out: 

•  AdBrite  (http://www.adbrite.com) 

•  Appsaholic  (http://apps.facebook.com/appsaholic/) 

•  BannerConnect  (http://www.bannerconnect.net) 

•  Chitika  (http://chitika.com/facebookapi.php) 

•  Cubics  (http://www.cubics.com) 

•  fbExchange  (http://fbexchange.com) 

•  Neverblue  (http://www.neverbluemedia.com) 

•  PeanutLabs  (http://www.peanutlabs.com) 

•  Survey  Savvy  (http://www.surveysawy.com) 

•  Zohark  Ads  (http://www.facebook.com/applications/Zohark_Ads/18584639088) 
If  I've  missed  your  company,  sincere  apologies! 

10.1.3  Selling  Your  Application 

Another  great  way  to  make  some  money  from  your  application  is  to  sell 
it.  Build  your  application  to  maturity  and  show  some  sustained  growth  or 
come  up  with  some  type  of  novel  method  that  has  a  lot  of  promise  to  attract 
buyers.  If  you  think  you've  developed  a  killer  application  that  has  a  lot  of 
potential  and,  for  whatever  reason,  you  want  to  sell  your  stake,  there  are  a 
few  websites  to  start  looking  for  a  buyer: 

•  Altura  (http://altura.com/) 

•  AppFactory  (http://www.baypartners.com/appfactory/) 

•  EBay  (http://www.ebay.com/)  □ 
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